ipmi.h

  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
 23struct module;
 24struct device;
 25
 26/*
 27 * Opaque type for a IPMI message user.  One of these is needed to
 28 * send and receive messages.
 29 */
 30struct 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 */
 39struct 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. */
 81void ipmi_free_recv_msg(struct ipmi_recv_msg *msg);
 82
 83struct 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. */
117int 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 */
130void ipmi_destroy_user(struct ipmi_user *user);
131
132/* Get the IPMI version of the BMC we are talking to. */
133int 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 */
146int ipmi_set_my_address(struct ipmi_user *user,
147			unsigned int  channel,
148			unsigned char address);
149int ipmi_get_my_address(struct ipmi_user *user,
150			unsigned int  channel,
151			unsigned char *address);
152int ipmi_set_my_LUN(struct ipmi_user *user,
153		    unsigned int  channel,
154		    unsigned char LUN);
155int 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 */
172int 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 */
190int 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 */
206void 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 */
217int ipmi_register_for_cmd(struct ipmi_user *user,
218			  unsigned char netfn,
219			  unsigned char cmd,
220			  unsigned int  chans);
221int 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 */
252int ipmi_get_maintenance_mode(struct ipmi_user *user);
253int 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 */
261int 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 */
268struct 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
287int ipmi_smi_watcher_register(struct ipmi_smi_watcher *watcher);
288int 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. */
296unsigned int ipmi_addr_length(int addr_type);
297
298/* Validate that the given IPMI address is valid. */
299int ipmi_validate_addr(struct ipmi_addr *addr, int len);
300
301/*
302 * How did the IPMI driver find out about the device?
303 */
304enum 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};
308const char *ipmi_addr_src_to_str(enum ipmi_addr_src src);
309
310union 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
322struct 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 */
340extern 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. */
345unsigned 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 */
353void 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 */