1 /*
2 * Texas Instruments System Control Interface Protocol
3 *
4 * Copyright (C) 2015-2016 Texas Instruments Incorporated - http://www.ti.com/
5 * Nishanth Menon
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License version 2 as
9 * published by the Free Software Foundation.
10 *
11 * This program is distributed "as is" WITHOUT ANY WARRANTY of any
12 * kind, whether express or implied; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 */
16
17 #ifndef __TISCI_PROTOCOL_H
18 #define __TISCI_PROTOCOL_H
19
20 /**
21 * struct ti_sci_version_info - version information structure
22 * @abi_major: Major ABI version. Change here implies risk of backward
23 * compatibility break.
24 * @abi_minor: Minor ABI version. Change here implies new feature addition,
25 * or compatible change in ABI.
26 * @firmware_revision: Firmware revision (not usually used).
27 * @firmware_description: Firmware description (not usually used).
28 */
29 struct ti_sci_version_info {
30 u8 abi_major;
31 u8 abi_minor;
32 u16 firmware_revision;
33 char firmware_description[32];
34 };
35
36 struct ti_sci_handle;
37
38 /**
39 * struct ti_sci_core_ops - SoC Core Operations
40 * @reboot_device: Reboot the SoC
41 * Returns 0 for successful request(ideally should never return),
42 * else returns corresponding error value.
43 */
44 struct ti_sci_core_ops {
45 int (*reboot_device)(const struct ti_sci_handle *handle);
46 };
47
48 /**
49 * struct ti_sci_dev_ops - Device control operations
50 * @get_device: Command to request for device managed by TISCI
51 * Returns 0 for successful exclusive request, else returns
52 * corresponding error message.
53 * @idle_device: Command to idle a device managed by TISCI
54 * Returns 0 for successful exclusive request, else returns
55 * corresponding error message.
56 * @put_device: Command to release a device managed by TISCI
57 * Returns 0 for successful release, else returns corresponding
58 * error message.
59 * @is_valid: Check if the device ID is a valid ID.
60 * Returns 0 if the ID is valid, else returns corresponding error.
61 * @get_context_loss_count: Command to retrieve context loss counter - this
62 * increments every time the device looses context. Overflow
63 * is possible.
64 * - count: pointer to u32 which will retrieve counter
65 * Returns 0 for successful information request and count has
66 * proper data, else returns corresponding error message.
67 * @is_idle: Reports back about device idle state
68 * - req_state: Returns requested idle state
69 * Returns 0 for successful information request and req_state and
70 * current_state has proper data, else returns corresponding error
71 * message.
72 * @is_stop: Reports back about device stop state
73 * - req_state: Returns requested stop state
74 * - current_state: Returns current stop state
75 * Returns 0 for successful information request and req_state and
76 * current_state has proper data, else returns corresponding error
77 * message.
78 * @is_on: Reports back about device ON(or active) state
79 * - req_state: Returns requested ON state
80 * - current_state: Returns current ON state
81 * Returns 0 for successful information request and req_state and
82 * current_state has proper data, else returns corresponding error
83 * message.
84 * @is_transitioning: Reports back if the device is in the middle of transition
85 * of state.
86 * -current_state: Returns 'true' if currently transitioning.
87 * @set_device_resets: Command to configure resets for device managed by TISCI.
88 * -reset_state: Device specific reset bit field
89 * Returns 0 for successful request, else returns
90 * corresponding error message.
91 * @get_device_resets: Command to read state of resets for device managed
92 * by TISCI.
93 * -reset_state: pointer to u32 which will retrieve resets
94 * Returns 0 for successful request, else returns
95 * corresponding error message.
96 *
97 * NOTE: for all these functions, the following parameters are generic in
98 * nature:
99 * -handle: Pointer to TISCI handle as retrieved by *ti_sci_get_handle
100 * -id: Device Identifier
101 *
102 * Request for the device - NOTE: the client MUST maintain integrity of
103 * usage count by balancing get_device with put_device. No refcounting is
104 * managed by driver for that purpose.
105 */
106 struct ti_sci_dev_ops {
107 int (*get_device)(const struct ti_sci_handle *handle, u32 id);
108 int (*idle_device)(const struct ti_sci_handle *handle, u32 id);
109 int (*put_device)(const struct ti_sci_handle *handle, u32 id);
110 int (*is_valid)(const struct ti_sci_handle *handle, u32 id);
111 int (*get_context_loss_count)(const struct ti_sci_handle *handle,
112 u32 id, u32 *count);
113 int (*is_idle)(const struct ti_sci_handle *handle, u32 id,
114 bool *requested_state);
115 int (*is_stop)(const struct ti_sci_handle *handle, u32 id,
116 bool *req_state, bool *current_state);
117 int (*is_on)(const struct ti_sci_handle *handle, u32 id,
118 bool *req_state, bool *current_state);
119 int (*is_transitioning)(const struct ti_sci_handle *handle, u32 id,
120 bool *current_state);
121 int (*set_device_resets)(const struct ti_sci_handle *handle, u32 id,
122 u32 reset_state);
123 int (*get_device_resets)(const struct ti_sci_handle *handle, u32 id,
124 u32 *reset_state);
125 };
126
127 /**
128 * struct ti_sci_clk_ops - Clock control operations
129 * @get_clock: Request for activation of clock and manage by processor
130 * - needs_ssc: 'true' if Spread Spectrum clock is desired.
131 * - can_change_freq: 'true' if frequency change is desired.
132 * - enable_input_term: 'true' if input termination is desired.
133 * @idle_clock: Request for Idling a clock managed by processor
134 * @put_clock: Release the clock to be auto managed by TISCI
135 * @is_auto: Is the clock being auto managed
136 * - req_state: state indicating if the clock is auto managed
137 * @is_on: Is the clock ON
138 * - req_state: if the clock is requested to be forced ON
139 * - current_state: if the clock is currently ON
140 * @is_off: Is the clock OFF
141 * - req_state: if the clock is requested to be forced OFF
142 * - current_state: if the clock is currently Gated
143 * @set_parent: Set the clock source of a specific device clock
144 * - parent_id: Parent clock identifier to set.
145 * @get_parent: Get the current clock source of a specific device clock
146 * - parent_id: Parent clock identifier which is the parent.
147 * @get_num_parents: Get the number of parents of the current clock source
148 * - num_parents: returns the number of parent clocks.
149 * @get_best_match_freq: Find a best matching frequency for a frequency
150 * range.
151 * - match_freq: Best matching frequency in Hz.
152 * @set_freq: Set the Clock frequency
153 * @get_freq: Get the Clock frequency
154 * - current_freq: Frequency in Hz that the clock is at.
155 *
156 * NOTE: for all these functions, the following parameters are generic in
157 * nature:
158 * -handle: Pointer to TISCI handle as retrieved by *ti_sci_get_handle
159 * -did: Device identifier this request is for
160 * -cid: Clock identifier for the device for this request.
161 * Each device has it's own set of clock inputs. This indexes
162 * which clock input to modify.
163 * -min_freq: The minimum allowable frequency in Hz. This is the minimum
164 * allowable programmed frequency and does not account for clock
165 * tolerances and jitter.
166 * -target_freq: The target clock frequency in Hz. A frequency will be
167 * processed as close to this target frequency as possible.
168 * -max_freq: The maximum allowable frequency in Hz. This is the maximum
169 * allowable programmed frequency and does not account for clock
170 * tolerances and jitter.
171 *
172 * Request for the clock - NOTE: the client MUST maintain integrity of
173 * usage count by balancing get_clock with put_clock. No refcounting is
174 * managed by driver for that purpose.
175 */
176 struct ti_sci_clk_ops {
177 int (*get_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid,
178 bool needs_ssc, bool can_change_freq,
179 bool enable_input_term);
180 int (*idle_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid);
181 int (*put_clock)(const struct ti_sci_handle *handle, u32 did, u8 cid);
182 int (*is_auto)(const struct ti_sci_handle *handle, u32 did, u8 cid,
183 bool *req_state);
184 int (*is_on)(const struct ti_sci_handle *handle, u32 did, u8 cid,
185 bool *req_state, bool *current_state);
186 int (*is_off)(const struct ti_sci_handle *handle, u32 did, u8 cid,
187 bool *req_state, bool *current_state);
188 int (*set_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid,
189 u8 parent_id);
190 int (*get_parent)(const struct ti_sci_handle *handle, u32 did, u8 cid,
191 u8 *parent_id);
192 int (*get_num_parents)(const struct ti_sci_handle *handle, u32 did,
193 u8 cid, u8 *num_parents);
194 int (*get_best_match_freq)(const struct ti_sci_handle *handle, u32 did,
195 u8 cid, u64 min_freq, u64 target_freq,
196 u64 max_freq, u64 *match_freq);
197 int (*set_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid,
198 u64 min_freq, u64 target_freq, u64 max_freq);
199 int (*get_freq)(const struct ti_sci_handle *handle, u32 did, u8 cid,
200 u64 *current_freq);
201 };
202
203 /**
204 * struct ti_sci_ops - Function support for TI SCI
205 * @dev_ops: Device specific operations
206 * @clk_ops: Clock specific operations
207 */
208 struct ti_sci_ops {
209 struct ti_sci_core_ops core_ops;
210 struct ti_sci_dev_ops dev_ops;
211 struct ti_sci_clk_ops clk_ops;
212 };
213
214 /**
215 * struct ti_sci_handle - Handle returned to TI SCI clients for usage.
216 * @version: structure containing version information
217 * @ops: operations that are made available to TI SCI clients
218 */
219 struct ti_sci_handle {
220 struct ti_sci_version_info version;
221 struct ti_sci_ops ops;
222 };
223
224 #if IS_ENABLED(CONFIG_TI_SCI_PROTOCOL)
225 const struct ti_sci_handle *ti_sci_get_handle(struct device *dev);
226 int ti_sci_put_handle(const struct ti_sci_handle *handle);
227 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev);
228
229 #else /* CONFIG_TI_SCI_PROTOCOL */
230
ti_sci_get_handle(struct device * dev)231 static inline const struct ti_sci_handle *ti_sci_get_handle(struct device *dev)
232 {
233 return ERR_PTR(-EINVAL);
234 }
235
ti_sci_put_handle(const struct ti_sci_handle * handle)236 static inline int ti_sci_put_handle(const struct ti_sci_handle *handle)
237 {
238 return -EINVAL;
239 }
240
241 static inline
devm_ti_sci_get_handle(struct device * dev)242 const struct ti_sci_handle *devm_ti_sci_get_handle(struct device *dev)
243 {
244 return ERR_PTR(-EINVAL);
245 }
246
247 #endif /* CONFIG_TI_SCI_PROTOCOL */
248
249 #endif /* __TISCI_PROTOCOL_H */
250