1 /* 2 * ipmi.h 3 * 4 * MontaVista IPMI interface 5 * 6 * Author: MontaVista Software, Inc. 7 * Corey Minyard <[email protected]> 8 * [email protected] 9 * 10 * Copyright 2002 MontaVista Software Inc. 11 * 12 * This program is free software; you can redistribute it and/or modify it 13 * under the terms of the GNU General Public License as published by the 14 * Free Software Foundation; either version 2 of the License, or (at your 15 * option) any later version. 16 * 17 * 18 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED 19 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 20 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 24 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 25 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 26 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 27 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 * 29 * You should have received a copy of the GNU General Public License along 30 * with this program; if not, write to the Free Software Foundation, Inc., 31 * 675 Mass Ave, Cambridge, MA 02139, USA. 32 */ 33 34 #ifndef __LINUX_IPMI_H 35 #define __LINUX_IPMI_H 36 37 #include <linux/ipmi_msgdefs.h> 38 #include <linux/compiler.h> 39 #include <linux/device.h> 40 41 /* 42 * This file describes an interface to an IPMI driver. You have to 43 * have a fairly good understanding of IPMI to use this, so go read 44 * the specs first before actually trying to do anything. 45 * 46 * With that said, this driver provides a multi-user interface to the 47 * IPMI driver, and it allows multiple IPMI physical interfaces below 48 * the driver. The physical interfaces bind as a lower layer on the 49 * driver. They appear as interfaces to the application using this 50 * interface. 51 * 52 * Multi-user means that multiple applications may use the driver, 53 * send commands, receive responses, etc. The driver keeps track of 54 * commands the user sends and tracks the responses. The responses 55 * will go back to the application that send the command. If the 56 * response doesn't come back in time, the driver will return a 57 * timeout error response to the application. Asynchronous events 58 * from the BMC event queue will go to all users bound to the driver. 59 * The incoming event queue in the BMC will automatically be flushed 60 * if it becomes full and it is queried once a second to see if 61 * anything is in it. Incoming commands to the driver will get 62 * delivered as commands. 63 * 64 * This driver provides two main interfaces: one for in-kernel 65 * applications and another for userland applications. The 66 * capabilities are basically the same for both interface, although 67 * the interfaces are somewhat different. The stuff in the 68 * #ifdef KERNEL below is the in-kernel interface. The userland 69 * interface is defined later in the file. */ 70 71 72 73 /* 74 * This is an overlay for all the address types, so it's easy to 75 * determine the actual address type. This is kind of like addresses 76 * work for sockets. 77 */ 78 #define IPMI_MAX_ADDR_SIZE 32 79 struct ipmi_addr 80 { 81 /* Try to take these from the "Channel Medium Type" table 82 in section 6.5 of the IPMI 1.5 manual. */ 83 int addr_type; 84 short channel; 85 char data[IPMI_MAX_ADDR_SIZE]; 86 }; 87 88 /* 89 * When the address is not used, the type will be set to this value. 90 * The channel is the BMC's channel number for the channel (usually 91 * 0), or IPMC_BMC_CHANNEL if communicating directly with the BMC. 92 */ 93 #define IPMI_SYSTEM_INTERFACE_ADDR_TYPE 0x0c 94 struct ipmi_system_interface_addr 95 { 96 int addr_type; 97 short channel; 98 unsigned char lun; 99 }; 100 101 /* An IPMB Address. */ 102 #define IPMI_IPMB_ADDR_TYPE 0x01 103 /* Used for broadcast get device id as described in section 17.9 of the 104 IPMI 1.5 manual. */ 105 #define IPMI_IPMB_BROADCAST_ADDR_TYPE 0x41 106 struct ipmi_ipmb_addr 107 { 108 int addr_type; 109 short channel; 110 unsigned char slave_addr; 111 unsigned char lun; 112 }; 113 114 /* 115 * A LAN Address. This is an address to/from a LAN interface bridged 116 * by the BMC, not an address actually out on the LAN. 117 * 118 * A concious decision was made here to deviate slightly from the IPMI 119 * spec. We do not use rqSWID and rsSWID like it shows in the 120 * message. Instead, we use remote_SWID and local_SWID. This means 121 * that any message (a request or response) from another device will 122 * always have exactly the same address. If you didn't do this, 123 * requests and responses from the same device would have different 124 * addresses, and that's not too cool. 125 * 126 * In this address, the remote_SWID is always the SWID the remote 127 * message came from, or the SWID we are sending the message to. 128 * local_SWID is always our SWID. Note that having our SWID in the 129 * message is a little weird, but this is required. 130 */ 131 #define IPMI_LAN_ADDR_TYPE 0x04 132 struct ipmi_lan_addr 133 { 134 int addr_type; 135 short channel; 136 unsigned char privilege; 137 unsigned char session_handle; 138 unsigned char remote_SWID; 139 unsigned char local_SWID; 140 unsigned char lun; 141 }; 142 143 144 /* 145 * Channel for talking directly with the BMC. When using this 146 * channel, This is for the system interface address type only. FIXME 147 * - is this right, or should we use -1? 148 */ 149 #define IPMI_BMC_CHANNEL 0xf 150 #define IPMI_NUM_CHANNELS 0x10 151 152 153 /* 154 * A raw IPMI message without any addressing. This covers both 155 * commands and responses. The completion code is always the first 156 * byte of data in the response (as the spec shows the messages laid 157 * out). 158 */ 159 struct ipmi_msg 160 { 161 unsigned char netfn; 162 unsigned char cmd; 163 unsigned short data_len; 164 unsigned char __user *data; 165 }; 166 167 struct kernel_ipmi_msg 168 { 169 unsigned char netfn; 170 unsigned char cmd; 171 unsigned short data_len; 172 unsigned char *data; 173 }; 174 175 /* 176 * Various defines that are useful for IPMI applications. 177 */ 178 #define IPMI_INVALID_CMD_COMPLETION_CODE 0xC1 179 #define IPMI_TIMEOUT_COMPLETION_CODE 0xC3 180 #define IPMI_UNKNOWN_ERR_COMPLETION_CODE 0xff 181 182 183 /* 184 * Receive types for messages coming from the receive interface. This 185 * is used for the receive in-kernel interface and in the receive 186 * IOCTL. 187 * 188 * The "IPMI_RESPONSE_RESPNOSE_TYPE" is a little strange sounding, but 189 * it allows you to get the message results when you send a response 190 * message. 191 */ 192 #define IPMI_RESPONSE_RECV_TYPE 1 /* A response to a command */ 193 #define IPMI_ASYNC_EVENT_RECV_TYPE 2 /* Something from the event queue */ 194 #define IPMI_CMD_RECV_TYPE 3 /* A command from somewhere else */ 195 #define IPMI_RESPONSE_RESPONSE_TYPE 4 /* The response for 196 a sent response, giving any 197 error status for sending the 198 response. When you send a 199 response message, this will 200 be returned. */ 201 /* Note that async events and received commands do not have a completion 202 code as the first byte of the incoming data, unlike a response. */ 203 204 205 206 #ifdef __KERNEL__ 207 208 /* 209 * The in-kernel interface. 210 */ 211 #include <linux/list.h> 212 #include <linux/module.h> 213 214 #ifdef CONFIG_PROC_FS 215 #include <linux/proc_fs.h> 216 extern struct proc_dir_entry *proc_ipmi_root; 217 #endif /* CONFIG_PROC_FS */ 218 219 /* Opaque type for a IPMI message user. One of these is needed to 220 send and receive messages. */ 221 typedef struct ipmi_user *ipmi_user_t; 222 223 /* 224 * Stuff coming from the receive interface comes as one of these. 225 * They are allocated, the receiver must free them with 226 * ipmi_free_recv_msg() when done with the message. The link is not 227 * used after the message is delivered, so the upper layer may use the 228 * link to build a linked list, if it likes. 229 */ 230 struct ipmi_recv_msg 231 { 232 struct list_head link; 233 234 /* The type of message as defined in the "Receive Types" 235 defines above. */ 236 int recv_type; 237 238 ipmi_user_t user; 239 struct ipmi_addr addr; 240 long msgid; 241 struct kernel_ipmi_msg msg; 242 243 /* The user_msg_data is the data supplied when a message was 244 sent, if this is a response to a sent message. If this is 245 not a response to a sent message, then user_msg_data will 246 be NULL. If the user above is NULL, then this will be the 247 intf. */ 248 void *user_msg_data; 249 250 /* Call this when done with the message. It will presumably free 251 the message and do any other necessary cleanup. */ 252 void (*done)(struct ipmi_recv_msg *msg); 253 254 /* Place-holder for the data, don't make any assumptions about 255 the size or existance of this, since it may change. */ 256 unsigned char msg_data[IPMI_MAX_MSG_LENGTH]; 257 }; 258 259 /* Allocate and free the receive message. */ 260 void ipmi_free_recv_msg(struct ipmi_recv_msg *msg); 261 262 struct ipmi_user_hndl 263 { 264 /* Routine type to call when a message needs to be routed to 265 the upper layer. This will be called with some locks held, 266 the only IPMI routines that can be called are ipmi_request 267 and the alloc/free operations. The handler_data is the 268 variable supplied when the receive handler was registered. */ 269 void (*ipmi_recv_hndl)(struct ipmi_recv_msg *msg, 270 void *user_msg_data); 271 272 /* Called when the interface detects a watchdog pre-timeout. If 273 this is NULL, it will be ignored for the user. */ 274 void (*ipmi_watchdog_pretimeout)(void *handler_data); 275 }; 276 277 /* Create a new user of the IPMI layer on the given interface number. */ 278 int ipmi_create_user(unsigned int if_num, 279 struct ipmi_user_hndl *handler, 280 void *handler_data, 281 ipmi_user_t *user); 282 283 /* Destroy the given user of the IPMI layer. Note that after this 284 function returns, the system is guaranteed to not call any 285 callbacks for the user. Thus as long as you destroy all the users 286 before you unload a module, you will be safe. And if you destroy 287 the users before you destroy the callback structures, it should be 288 safe, too. */ 289 int ipmi_destroy_user(ipmi_user_t user); 290 291 /* Get the IPMI version of the BMC we are talking to. */ 292 void ipmi_get_version(ipmi_user_t user, 293 unsigned char *major, 294 unsigned char *minor); 295 296 /* Set and get the slave address and LUN that we will use for our 297 source messages. Note that this affects the interface, not just 298 this user, so it will affect all users of this interface. This is 299 so some initialization code can come in and do the OEM-specific 300 things it takes to determine your address (if not the BMC) and set 301 it for everyone else. Note that each channel can have its own address. */ 302 int ipmi_set_my_address(ipmi_user_t user, 303 unsigned int channel, 304 unsigned char address); 305 int ipmi_get_my_address(ipmi_user_t user, 306 unsigned int channel, 307 unsigned char *address); 308 int ipmi_set_my_LUN(ipmi_user_t user, 309 unsigned int channel, 310 unsigned char LUN); 311 int ipmi_get_my_LUN(ipmi_user_t user, 312 unsigned int channel, 313 unsigned char *LUN); 314 315 /* 316 * Like ipmi_request, but lets you specify the number of retries and 317 * the retry time. The retries is the number of times the message 318 * will be resent if no reply is received. If set to -1, the default 319 * value will be used. The retry time is the time in milliseconds 320 * between retries. If set to zero, the default value will be 321 * used. 322 * 323 * Don't use this unless you *really* have to. It's primarily for the 324 * IPMI over LAN converter; since the LAN stuff does its own retries, 325 * it makes no sense to do it here. However, this can be used if you 326 * have unusual requirements. 327 */ 328 int ipmi_request_settime(ipmi_user_t user, 329 struct ipmi_addr *addr, 330 long msgid, 331 struct kernel_ipmi_msg *msg, 332 void *user_msg_data, 333 int priority, 334 int max_retries, 335 unsigned int retry_time_ms); 336 337 /* 338 * Like ipmi_request, but with messages supplied. This will not 339 * allocate any memory, and the messages may be statically allocated 340 * (just make sure to do the "done" handling on them). Note that this 341 * is primarily for the watchdog timer, since it should be able to 342 * send messages even if no memory is available. This is subject to 343 * change as the system changes, so don't use it unless you REALLY 344 * have to. 345 */ 346 int ipmi_request_supply_msgs(ipmi_user_t user, 347 struct ipmi_addr *addr, 348 long msgid, 349 struct kernel_ipmi_msg *msg, 350 void *user_msg_data, 351 void *supplied_smi, 352 struct ipmi_recv_msg *supplied_recv, 353 int priority); 354 355 /* 356 * When commands come in to the SMS, the user can register to receive 357 * them. Only one user can be listening on a specific netfn/cmd pair 358 * at a time, you will get an EBUSY error if the command is already 359 * registered. If a command is received that does not have a user 360 * registered, the driver will automatically return the proper 361 * error. 362 */ 363 int ipmi_register_for_cmd(ipmi_user_t user, 364 unsigned char netfn, 365 unsigned char cmd); 366 int ipmi_unregister_for_cmd(ipmi_user_t user, 367 unsigned char netfn, 368 unsigned char cmd); 369 370 /* 371 * Allow run-to-completion mode to be set for the interface of 372 * a specific user. 373 */ 374 void ipmi_user_set_run_to_completion(ipmi_user_t user, int val); 375 376 /* 377 * When the user is created, it will not receive IPMI events by 378 * default. The user must set this to TRUE to get incoming events. 379 * The first user that sets this to TRUE will receive all events that 380 * have been queued while no one was waiting for events. 381 */ 382 int ipmi_set_gets_events(ipmi_user_t user, int val); 383 384 /* 385 * Called when a new SMI is registered. This will also be called on 386 * every existing interface when a new watcher is registered with 387 * ipmi_smi_watcher_register(). 388 */ 389 struct ipmi_smi_watcher 390 { 391 struct list_head link; 392 393 /* You must set the owner to the current module, if you are in 394 a module (generally just set it to "THIS_MODULE"). */ 395 struct module *owner; 396 397 /* These two are called with read locks held for the interface 398 the watcher list. So you can add and remove users from the 399 IPMI interface, send messages, etc., but you cannot add 400 or remove SMI watchers or SMI interfaces. */ 401 void (*new_smi)(int if_num, struct device *dev); 402 void (*smi_gone)(int if_num); 403 }; 404 405 int ipmi_smi_watcher_register(struct ipmi_smi_watcher *watcher); 406 int ipmi_smi_watcher_unregister(struct ipmi_smi_watcher *watcher); 407 408 /* The following are various helper functions for dealing with IPMI 409 addresses. */ 410 411 /* Return the maximum length of an IPMI address given it's type. */ 412 unsigned int ipmi_addr_length(int addr_type); 413 414 /* Validate that the given IPMI address is valid. */ 415 int ipmi_validate_addr(struct ipmi_addr *addr, int len); 416 417 #endif /* __KERNEL__ */ 418 419 420 /* 421 * The userland interface 422 */ 423 424 /* 425 * The userland interface for the IPMI driver is a standard character 426 * device, with each instance of an interface registered as a minor 427 * number under the major character device. 428 * 429 * The read and write calls do not work, to get messages in and out 430 * requires ioctl calls because of the complexity of the data. select 431 * and poll do work, so you can wait for input using the file 432 * descriptor, you just can use read to get it. 433 * 434 * In general, you send a command down to the interface and receive 435 * responses back. You can use the msgid value to correlate commands 436 * and responses, the driver will take care of figuring out which 437 * incoming messages are for which command and find the proper msgid 438 * value to report. You will only receive reponses for commands you 439 * send. Asynchronous events, however, go to all open users, so you 440 * must be ready to handle these (or ignore them if you don't care). 441 * 442 * The address type depends upon the channel type. When talking 443 * directly to the BMC (IPMC_BMC_CHANNEL), the address is ignored 444 * (IPMI_UNUSED_ADDR_TYPE). When talking to an IPMB channel, you must 445 * supply a valid IPMB address with the addr_type set properly. 446 * 447 * When talking to normal channels, the driver takes care of the 448 * details of formatting and sending messages on that channel. You do 449 * not, for instance, have to format a send command, you just send 450 * whatever command you want to the channel, the driver will create 451 * the send command, automatically issue receive command and get even 452 * commands, and pass those up to the proper user. 453 */ 454 455 456 /* The magic IOCTL value for this interface. */ 457 #define IPMI_IOC_MAGIC 'i' 458 459 460 /* Messages sent to the interface are this format. */ 461 struct ipmi_req 462 { 463 unsigned char __user *addr; /* Address to send the message to. */ 464 unsigned int addr_len; 465 466 long msgid; /* The sequence number for the message. This 467 exact value will be reported back in the 468 response to this request if it is a command. 469 If it is a response, this will be used as 470 the sequence value for the response. */ 471 472 struct ipmi_msg msg; 473 }; 474 /* 475 * Send a message to the interfaces. error values are: 476 * - EFAULT - an address supplied was invalid. 477 * - EINVAL - The address supplied was not valid, or the command 478 * was not allowed. 479 * - EMSGSIZE - The message to was too large. 480 * - ENOMEM - Buffers could not be allocated for the command. 481 */ 482 #define IPMICTL_SEND_COMMAND _IOR(IPMI_IOC_MAGIC, 13, \ 483 struct ipmi_req) 484 485 /* Messages sent to the interface with timing parameters are this 486 format. */ 487 struct ipmi_req_settime 488 { 489 struct ipmi_req req; 490 491 /* See ipmi_request_settime() above for details on these 492 values. */ 493 int retries; 494 unsigned int retry_time_ms; 495 }; 496 /* 497 * Send a message to the interfaces with timing parameters. error values 498 * are: 499 * - EFAULT - an address supplied was invalid. 500 * - EINVAL - The address supplied was not valid, or the command 501 * was not allowed. 502 * - EMSGSIZE - The message to was too large. 503 * - ENOMEM - Buffers could not be allocated for the command. 504 */ 505 #define IPMICTL_SEND_COMMAND_SETTIME _IOR(IPMI_IOC_MAGIC, 21, \ 506 struct ipmi_req_settime) 507 508 /* Messages received from the interface are this format. */ 509 struct ipmi_recv 510 { 511 int recv_type; /* Is this a command, response or an 512 asyncronous event. */ 513 514 unsigned char __user *addr; /* Address the message was from is put 515 here. The caller must supply the 516 memory. */ 517 unsigned int addr_len; /* The size of the address buffer. 518 The caller supplies the full buffer 519 length, this value is updated to 520 the actual message length when the 521 message is received. */ 522 523 long msgid; /* The sequence number specified in the request 524 if this is a response. If this is a command, 525 this will be the sequence number from the 526 command. */ 527 528 struct ipmi_msg msg; /* The data field must point to a buffer. 529 The data_size field must be set to the 530 size of the message buffer. The 531 caller supplies the full buffer 532 length, this value is updated to the 533 actual message length when the message 534 is received. */ 535 }; 536 537 /* 538 * Receive a message. error values: 539 * - EAGAIN - no messages in the queue. 540 * - EFAULT - an address supplied was invalid. 541 * - EINVAL - The address supplied was not valid. 542 * - EMSGSIZE - The message to was too large to fit into the message buffer, 543 * the message will be left in the buffer. */ 544 #define IPMICTL_RECEIVE_MSG _IOWR(IPMI_IOC_MAGIC, 12, \ 545 struct ipmi_recv) 546 547 /* 548 * Like RECEIVE_MSG, but if the message won't fit in the buffer, it 549 * will truncate the contents instead of leaving the data in the 550 * buffer. 551 */ 552 #define IPMICTL_RECEIVE_MSG_TRUNC _IOWR(IPMI_IOC_MAGIC, 11, \ 553 struct ipmi_recv) 554 555 /* Register to get commands from other entities on this interface. */ 556 struct ipmi_cmdspec 557 { 558 unsigned char netfn; 559 unsigned char cmd; 560 }; 561 562 /* 563 * Register to receive a specific command. error values: 564 * - EFAULT - an address supplied was invalid. 565 * - EBUSY - The netfn/cmd supplied was already in use. 566 * - ENOMEM - could not allocate memory for the entry. 567 */ 568 #define IPMICTL_REGISTER_FOR_CMD _IOR(IPMI_IOC_MAGIC, 14, \ 569 struct ipmi_cmdspec) 570 /* 571 * Unregister a regsitered command. error values: 572 * - EFAULT - an address supplied was invalid. 573 * - ENOENT - The netfn/cmd was not found registered for this user. 574 */ 575 #define IPMICTL_UNREGISTER_FOR_CMD _IOR(IPMI_IOC_MAGIC, 15, \ 576 struct ipmi_cmdspec) 577 578 /* 579 * Set whether this interface receives events. Note that the first 580 * user registered for events will get all pending events for the 581 * interface. error values: 582 * - EFAULT - an address supplied was invalid. 583 */ 584 #define IPMICTL_SET_GETS_EVENTS_CMD _IOR(IPMI_IOC_MAGIC, 16, int) 585 586 /* 587 * Set and get the slave address and LUN that we will use for our 588 * source messages. Note that this affects the interface, not just 589 * this user, so it will affect all users of this interface. This is 590 * so some initialization code can come in and do the OEM-specific 591 * things it takes to determine your address (if not the BMC) and set 592 * it for everyone else. You should probably leave the LUN alone. 593 */ 594 struct ipmi_channel_lun_address_set 595 { 596 unsigned short channel; 597 unsigned char value; 598 }; 599 #define IPMICTL_SET_MY_CHANNEL_ADDRESS_CMD _IOR(IPMI_IOC_MAGIC, 24, struct ipmi_channel_lun_address_set) 600 #define IPMICTL_GET_MY_CHANNEL_ADDRESS_CMD _IOR(IPMI_IOC_MAGIC, 25, struct ipmi_channel_lun_address_set) 601 #define IPMICTL_SET_MY_CHANNEL_LUN_CMD _IOR(IPMI_IOC_MAGIC, 26, struct ipmi_channel_lun_address_set) 602 #define IPMICTL_GET_MY_CHANNEL_LUN_CMD _IOR(IPMI_IOC_MAGIC, 27, struct ipmi_channel_lun_address_set) 603 /* Legacy interfaces, these only set IPMB 0. */ 604 #define IPMICTL_SET_MY_ADDRESS_CMD _IOR(IPMI_IOC_MAGIC, 17, unsigned int) 605 #define IPMICTL_GET_MY_ADDRESS_CMD _IOR(IPMI_IOC_MAGIC, 18, unsigned int) 606 #define IPMICTL_SET_MY_LUN_CMD _IOR(IPMI_IOC_MAGIC, 19, unsigned int) 607 #define IPMICTL_GET_MY_LUN_CMD _IOR(IPMI_IOC_MAGIC, 20, unsigned int) 608 609 /* 610 * Get/set the default timing values for an interface. You shouldn't 611 * generally mess with these. 612 */ 613 struct ipmi_timing_parms 614 { 615 int retries; 616 unsigned int retry_time_ms; 617 }; 618 #define IPMICTL_SET_TIMING_PARMS_CMD _IOR(IPMI_IOC_MAGIC, 22, \ 619 struct ipmi_timing_parms) 620 #define IPMICTL_GET_TIMING_PARMS_CMD _IOR(IPMI_IOC_MAGIC, 23, \ 621 struct ipmi_timing_parms) 622 623 #endif /* __LINUX_IPMI_H */ 624