1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * ipmi_si_sm.h
4  *
5  * State machine interface for low-level IPMI system management
6  * interface state machines.  This code is the interface between
7  * the ipmi_smi code (that handles the policy of a KCS, SMIC, or
8  * BT interface) and the actual low-level state machine.
9  *
10  * Author: MontaVista Software, Inc.
11  *         Corey Minyard <minyard@mvista.com>
12  *         source@mvista.com
13  *
14  * Copyright 2002 MontaVista Software Inc.
15  */
16 
17 #ifndef __IPMI_SI_SM_H__
18 #define __IPMI_SI_SM_H__
19 
20 #include "ipmi_si.h"
21 
22 /*
23  * This is defined by the state machines themselves, it is an opaque
24  * data type for them to use.
25  */
26 struct si_sm_data;
27 
28 /* Results of SMI events. */
29 enum si_sm_result {
30 	SI_SM_CALL_WITHOUT_DELAY, /* Call the driver again immediately */
31 	SI_SM_CALL_WITH_DELAY,	/* Delay some before calling again. */
32 	SI_SM_CALL_WITH_TICK_DELAY,/* Delay >=1 tick before calling again. */
33 	SI_SM_TRANSACTION_COMPLETE, /* A transaction is finished. */
34 	SI_SM_IDLE,		/* The SM is in idle state. */
35 	SI_SM_HOSED,		/* The hardware violated the state machine. */
36 
37 	/*
38 	 * The hardware is asserting attn and the state machine is
39 	 * idle.
40 	 */
41 	SI_SM_ATTN
42 };
43 
44 /* Handlers for the SMI state machine. */
45 struct si_sm_handlers {
46 	/*
47 	 * Put the version number of the state machine here so the
48 	 * upper layer can print it.
49 	 */
50 	char *version;
51 
52 	/*
53 	 * Initialize the data and return the amount of I/O space to
54 	 * reserve for the space.
55 	 */
56 	unsigned int (*init_data)(struct si_sm_data *smi,
57 				  struct si_sm_io   *io);
58 
59 	/*
60 	 * Start a new transaction in the state machine.  This will
61 	 * return -2 if the state machine is not idle, -1 if the size
62 	 * is invalid (to large or too small), or 0 if the transaction
63 	 * is successfully completed.
64 	 */
65 	int (*start_transaction)(struct si_sm_data *smi,
66 				 unsigned char *data, unsigned int size);
67 
68 	/*
69 	 * Return the results after the transaction.  This will return
70 	 * -1 if the buffer is too small, zero if no transaction is
71 	 * present, or the actual length of the result data.
72 	 */
73 	int (*get_result)(struct si_sm_data *smi,
74 			  unsigned char *data, unsigned int length);
75 
76 	/*
77 	 * Call this periodically (for a polled interface) or upon
78 	 * receiving an interrupt (for a interrupt-driven interface).
79 	 * If interrupt driven, you should probably poll this
80 	 * periodically when not in idle state.  This should be called
81 	 * with the time that passed since the last call, if it is
82 	 * significant.  Time is in microseconds.
83 	 */
84 	enum si_sm_result (*event)(struct si_sm_data *smi, long time);
85 
86 	/*
87 	 * Attempt to detect an SMI.  Returns 0 on success or nonzero
88 	 * on failure.
89 	 */
90 	int (*detect)(struct si_sm_data *smi);
91 
92 	/* The interface is shutting down, so clean it up. */
93 	void (*cleanup)(struct si_sm_data *smi);
94 
95 	/* Return the size of the SMI structure in bytes. */
96 	int (*size)(void);
97 };
98 
99 /* Current state machines that we can use. */
100 extern const struct si_sm_handlers kcs_smi_handlers;
101 extern const struct si_sm_handlers smic_smi_handlers;
102 extern const struct si_sm_handlers bt_smi_handlers;
103 
104 #endif /* __IPMI_SI_SM_H__ */
105