ipmi.h 11 KB

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