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