1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* |
3 | * Surface System Aggregator Module (SSAM) controller interface. |
4 | * |
5 | * Main communication interface for the SSAM EC. Provides a controller |
6 | * managing access and communication to and from the SSAM EC, as well as main |
7 | * communication structures and definitions. |
8 | * |
9 | * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com> |
10 | */ |
11 | |
12 | #ifndef _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H |
13 | #define _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H |
14 | |
15 | #include <linux/completion.h> |
16 | #include <linux/device.h> |
17 | #include <linux/types.h> |
18 | |
19 | #include <linux/surface_aggregator/serial_hub.h> |
20 | |
21 | |
22 | /* -- Main data types and definitions --------------------------------------- */ |
23 | |
24 | /** |
25 | * enum ssam_event_flags - Flags for enabling/disabling SAM events |
26 | * @SSAM_EVENT_SEQUENCED: The event will be sent via a sequenced data frame. |
27 | */ |
28 | enum ssam_event_flags { |
29 | SSAM_EVENT_SEQUENCED = BIT(0), |
30 | }; |
31 | |
32 | /** |
33 | * struct ssam_event - SAM event sent from the EC to the host. |
34 | * @target_category: Target category of the event source. See &enum ssam_ssh_tc. |
35 | * @target_id: Target ID of the event source. |
36 | * @command_id: Command ID of the event. |
37 | * @instance_id: Instance ID of the event source. |
38 | * @length: Length of the event payload in bytes. |
39 | * @data: Event payload data. |
40 | */ |
41 | struct ssam_event { |
42 | u8 target_category; |
43 | u8 target_id; |
44 | u8 command_id; |
45 | u8 instance_id; |
46 | u16 length; |
47 | u8 data[] __counted_by(length); |
48 | }; |
49 | |
50 | /** |
51 | * enum ssam_request_flags - Flags for SAM requests. |
52 | * |
53 | * @SSAM_REQUEST_HAS_RESPONSE: |
54 | * Specifies that the request expects a response. If not set, the request |
55 | * will be directly completed after its underlying packet has been |
56 | * transmitted. If set, the request transport system waits for a response |
57 | * of the request. |
58 | * |
59 | * @SSAM_REQUEST_UNSEQUENCED: |
60 | * Specifies that the request should be transmitted via an unsequenced |
61 | * packet. If set, the request must not have a response, meaning that this |
62 | * flag and the %SSAM_REQUEST_HAS_RESPONSE flag are mutually exclusive. |
63 | */ |
64 | enum ssam_request_flags { |
65 | SSAM_REQUEST_HAS_RESPONSE = BIT(0), |
66 | SSAM_REQUEST_UNSEQUENCED = BIT(1), |
67 | }; |
68 | |
69 | /** |
70 | * struct ssam_request - SAM request description. |
71 | * @target_category: Category of the request's target. See &enum ssam_ssh_tc. |
72 | * @target_id: ID of the request's target. |
73 | * @command_id: Command ID of the request. |
74 | * @instance_id: Instance ID of the request's target. |
75 | * @flags: Flags for the request. See &enum ssam_request_flags. |
76 | * @length: Length of the request payload in bytes. |
77 | * @payload: Request payload data. |
78 | * |
79 | * This struct fully describes a SAM request with payload. It is intended to |
80 | * help set up the actual transport struct, e.g. &struct ssam_request_sync, |
81 | * and specifically its raw message data via ssam_request_write_data(). |
82 | */ |
83 | struct ssam_request { |
84 | u8 target_category; |
85 | u8 target_id; |
86 | u8 command_id; |
87 | u8 instance_id; |
88 | u16 flags; |
89 | u16 length; |
90 | const u8 *payload; |
91 | }; |
92 | |
93 | /** |
94 | * struct ssam_response - Response buffer for SAM request. |
95 | * @capacity: Capacity of the buffer, in bytes. |
96 | * @length: Length of the actual data stored in the memory pointed to by |
97 | * @pointer, in bytes. Set by the transport system. |
98 | * @pointer: Pointer to the buffer's memory, storing the response payload data. |
99 | */ |
100 | struct ssam_response { |
101 | size_t capacity; |
102 | size_t length; |
103 | u8 *pointer; |
104 | }; |
105 | |
106 | struct ssam_controller; |
107 | |
108 | struct ssam_controller *ssam_get_controller(void); |
109 | struct ssam_controller *ssam_client_bind(struct device *client); |
110 | int ssam_client_link(struct ssam_controller *ctrl, struct device *client); |
111 | |
112 | struct device *ssam_controller_device(struct ssam_controller *c); |
113 | |
114 | struct ssam_controller *ssam_controller_get(struct ssam_controller *c); |
115 | void ssam_controller_put(struct ssam_controller *c); |
116 | |
117 | void ssam_controller_statelock(struct ssam_controller *c); |
118 | void ssam_controller_stateunlock(struct ssam_controller *c); |
119 | |
120 | ssize_t ssam_request_write_data(struct ssam_span *buf, |
121 | struct ssam_controller *ctrl, |
122 | const struct ssam_request *spec); |
123 | |
124 | |
125 | /* -- Synchronous request interface. ---------------------------------------- */ |
126 | |
127 | /** |
128 | * struct ssam_request_sync - Synchronous SAM request struct. |
129 | * @base: Underlying SSH request. |
130 | * @comp: Completion used to signal full completion of the request. After the |
131 | * request has been submitted, this struct may only be modified or |
132 | * deallocated after the completion has been signaled. |
133 | * request has been submitted, |
134 | * @resp: Buffer to store the response. |
135 | * @status: Status of the request, set after the base request has been |
136 | * completed or has failed. |
137 | */ |
138 | struct ssam_request_sync { |
139 | struct ssh_request base; |
140 | struct completion comp; |
141 | struct ssam_response *resp; |
142 | int status; |
143 | }; |
144 | |
145 | int ssam_request_sync_alloc(size_t payload_len, gfp_t flags, |
146 | struct ssam_request_sync **rqst, |
147 | struct ssam_span *buffer); |
148 | |
149 | void ssam_request_sync_free(struct ssam_request_sync *rqst); |
150 | |
151 | int ssam_request_sync_init(struct ssam_request_sync *rqst, |
152 | enum ssam_request_flags flags); |
153 | |
154 | /** |
155 | * ssam_request_sync_set_data - Set message data of a synchronous request. |
156 | * @rqst: The request. |
157 | * @ptr: Pointer to the request message data. |
158 | * @len: Length of the request message data. |
159 | * |
160 | * Set the request message data of a synchronous request. The provided buffer |
161 | * needs to live until the request has been completed. |
162 | */ |
163 | static inline void ssam_request_sync_set_data(struct ssam_request_sync *rqst, |
164 | u8 *ptr, size_t len) |
165 | { |
166 | ssh_request_set_data(r: &rqst->base, ptr, len); |
167 | } |
168 | |
169 | /** |
170 | * ssam_request_sync_set_resp - Set response buffer of a synchronous request. |
171 | * @rqst: The request. |
172 | * @resp: The response buffer. |
173 | * |
174 | * Sets the response buffer of a synchronous request. This buffer will store |
175 | * the response of the request after it has been completed. May be %NULL if no |
176 | * response is expected. |
177 | */ |
178 | static inline void ssam_request_sync_set_resp(struct ssam_request_sync *rqst, |
179 | struct ssam_response *resp) |
180 | { |
181 | rqst->resp = resp; |
182 | } |
183 | |
184 | int ssam_request_sync_submit(struct ssam_controller *ctrl, |
185 | struct ssam_request_sync *rqst); |
186 | |
187 | /** |
188 | * ssam_request_sync_wait - Wait for completion of a synchronous request. |
189 | * @rqst: The request to wait for. |
190 | * |
191 | * Wait for completion and release of a synchronous request. After this |
192 | * function terminates, the request is guaranteed to have left the transport |
193 | * system. After successful submission of a request, this function must be |
194 | * called before accessing the response of the request, freeing the request, |
195 | * or freeing any of the buffers associated with the request. |
196 | * |
197 | * This function must not be called if the request has not been submitted yet |
198 | * and may lead to a deadlock/infinite wait if a subsequent request submission |
199 | * fails in that case, due to the completion never triggering. |
200 | * |
201 | * Return: Returns the status of the given request, which is set on completion |
202 | * of the packet. This value is zero on success and negative on failure. |
203 | */ |
204 | static inline int ssam_request_sync_wait(struct ssam_request_sync *rqst) |
205 | { |
206 | wait_for_completion(&rqst->comp); |
207 | return rqst->status; |
208 | } |
209 | |
210 | int ssam_request_do_sync(struct ssam_controller *ctrl, |
211 | const struct ssam_request *spec, |
212 | struct ssam_response *rsp); |
213 | |
214 | int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl, |
215 | const struct ssam_request *spec, |
216 | struct ssam_response *rsp, |
217 | struct ssam_span *buf); |
218 | |
219 | /** |
220 | * ssam_request_do_sync_onstack - Execute a synchronous request on the stack. |
221 | * @ctrl: The controller via which the request is submitted. |
222 | * @rqst: The request specification. |
223 | * @rsp: The response buffer. |
224 | * @payload_len: The (maximum) request payload length. |
225 | * |
226 | * Allocates a synchronous request with specified payload length on the stack, |
227 | * fully initializes it via the provided request specification, submits it, |
228 | * and finally waits for its completion before returning its status. This |
229 | * helper macro essentially allocates the request message buffer on the stack |
230 | * and then calls ssam_request_do_sync_with_buffer(). |
231 | * |
232 | * Note: The @payload_len parameter specifies the maximum payload length, used |
233 | * for buffer allocation. The actual payload length may be smaller. |
234 | * |
235 | * Return: Returns the status of the request or any failure during setup, i.e. |
236 | * zero on success and a negative value on failure. |
237 | */ |
238 | #define ssam_request_do_sync_onstack(ctrl, rqst, rsp, payload_len) \ |
239 | ({ \ |
240 | u8 __data[SSH_COMMAND_MESSAGE_LENGTH(payload_len)]; \ |
241 | struct ssam_span __buf = { &__data[0], ARRAY_SIZE(__data) }; \ |
242 | \ |
243 | ssam_request_do_sync_with_buffer(ctrl, rqst, rsp, &__buf); \ |
244 | }) |
245 | |
246 | /** |
247 | * __ssam_retry - Retry request in case of I/O errors or timeouts. |
248 | * @request: The request function to execute. Must return an integer. |
249 | * @n: Number of tries. |
250 | * @args: Arguments for the request function. |
251 | * |
252 | * Executes the given request function, i.e. calls @request. In case the |
253 | * request returns %-EREMOTEIO (indicates I/O error) or %-ETIMEDOUT (request |
254 | * or underlying packet timed out), @request will be re-executed again, up to |
255 | * @n times in total. |
256 | * |
257 | * Return: Returns the return value of the last execution of @request. |
258 | */ |
259 | #define __ssam_retry(request, n, args...) \ |
260 | ({ \ |
261 | int __i, __s = 0; \ |
262 | \ |
263 | for (__i = (n); __i > 0; __i--) { \ |
264 | __s = request(args); \ |
265 | if (__s != -ETIMEDOUT && __s != -EREMOTEIO) \ |
266 | break; \ |
267 | } \ |
268 | __s; \ |
269 | }) |
270 | |
271 | /** |
272 | * ssam_retry - Retry request in case of I/O errors or timeouts up to three |
273 | * times in total. |
274 | * @request: The request function to execute. Must return an integer. |
275 | * @args: Arguments for the request function. |
276 | * |
277 | * Executes the given request function, i.e. calls @request. In case the |
278 | * request returns %-EREMOTEIO (indicates I/O error) or -%ETIMEDOUT (request |
279 | * or underlying packet timed out), @request will be re-executed again, up to |
280 | * three times in total. |
281 | * |
282 | * See __ssam_retry() for a more generic macro for this purpose. |
283 | * |
284 | * Return: Returns the return value of the last execution of @request. |
285 | */ |
286 | #define ssam_retry(request, args...) \ |
287 | __ssam_retry(request, 3, args) |
288 | |
289 | /** |
290 | * struct ssam_request_spec - Blue-print specification of SAM request. |
291 | * @target_category: Category of the request's target. See &enum ssam_ssh_tc. |
292 | * @target_id: ID of the request's target. |
293 | * @command_id: Command ID of the request. |
294 | * @instance_id: Instance ID of the request's target. |
295 | * @flags: Flags for the request. See &enum ssam_request_flags. |
296 | * |
297 | * Blue-print specification for a SAM request. This struct describes the |
298 | * unique static parameters of a request (i.e. type) without specifying any of |
299 | * its instance-specific data (e.g. payload). It is intended to be used as base |
300 | * for defining simple request functions via the |
301 | * ``SSAM_DEFINE_SYNC_REQUEST_x()`` family of macros. |
302 | */ |
303 | struct ssam_request_spec { |
304 | u8 target_category; |
305 | u8 target_id; |
306 | u8 command_id; |
307 | u8 instance_id; |
308 | u8 flags; |
309 | }; |
310 | |
311 | /** |
312 | * struct ssam_request_spec_md - Blue-print specification for multi-device SAM |
313 | * request. |
314 | * @target_category: Category of the request's target. See &enum ssam_ssh_tc. |
315 | * @command_id: Command ID of the request. |
316 | * @flags: Flags for the request. See &enum ssam_request_flags. |
317 | * |
318 | * Blue-print specification for a multi-device SAM request, i.e. a request |
319 | * that is applicable to multiple device instances, described by their |
320 | * individual target and instance IDs. This struct describes the unique static |
321 | * parameters of a request (i.e. type) without specifying any of its |
322 | * instance-specific data (e.g. payload) and without specifying any of its |
323 | * device specific IDs (i.e. target and instance ID). It is intended to be |
324 | * used as base for defining simple multi-device request functions via the |
325 | * ``SSAM_DEFINE_SYNC_REQUEST_MD_x()`` and ``SSAM_DEFINE_SYNC_REQUEST_CL_x()`` |
326 | * families of macros. |
327 | */ |
328 | struct ssam_request_spec_md { |
329 | u8 target_category; |
330 | u8 command_id; |
331 | u8 flags; |
332 | }; |
333 | |
334 | /** |
335 | * SSAM_DEFINE_SYNC_REQUEST_N() - Define synchronous SAM request function |
336 | * with neither argument nor return value. |
337 | * @name: Name of the generated function. |
338 | * @spec: Specification (&struct ssam_request_spec) defining the request. |
339 | * |
340 | * Defines a function executing the synchronous SAM request specified by |
341 | * @spec, with the request having neither argument nor return value. The |
342 | * generated function takes care of setting up the request struct and buffer |
343 | * allocation, as well as execution of the request itself, returning once the |
344 | * request has been fully completed. The required transport buffer will be |
345 | * allocated on the stack. |
346 | * |
347 | * The generated function is defined as ``static int name(struct |
348 | * ssam_controller *ctrl)``, returning the status of the request, which is |
349 | * zero on success and negative on failure. The ``ctrl`` parameter is the |
350 | * controller via which the request is being sent. |
351 | * |
352 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
353 | * the generated function. |
354 | */ |
355 | #define SSAM_DEFINE_SYNC_REQUEST_N(name, spec...) \ |
356 | static int name(struct ssam_controller *ctrl) \ |
357 | { \ |
358 | struct ssam_request_spec s = (struct ssam_request_spec)spec; \ |
359 | struct ssam_request rqst; \ |
360 | \ |
361 | rqst.target_category = s.target_category; \ |
362 | rqst.target_id = s.target_id; \ |
363 | rqst.command_id = s.command_id; \ |
364 | rqst.instance_id = s.instance_id; \ |
365 | rqst.flags = s.flags; \ |
366 | rqst.length = 0; \ |
367 | rqst.payload = NULL; \ |
368 | \ |
369 | return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \ |
370 | } |
371 | |
372 | /** |
373 | * SSAM_DEFINE_SYNC_REQUEST_W() - Define synchronous SAM request function with |
374 | * argument. |
375 | * @name: Name of the generated function. |
376 | * @atype: Type of the request's argument. |
377 | * @spec: Specification (&struct ssam_request_spec) defining the request. |
378 | * |
379 | * Defines a function executing the synchronous SAM request specified by |
380 | * @spec, with the request taking an argument of type @atype and having no |
381 | * return value. The generated function takes care of setting up the request |
382 | * struct, buffer allocation, as well as execution of the request itself, |
383 | * returning once the request has been fully completed. The required transport |
384 | * buffer will be allocated on the stack. |
385 | * |
386 | * The generated function is defined as ``static int name(struct |
387 | * ssam_controller *ctrl, const atype *arg)``, returning the status of the |
388 | * request, which is zero on success and negative on failure. The ``ctrl`` |
389 | * parameter is the controller via which the request is sent. The request |
390 | * argument is specified via the ``arg`` pointer. |
391 | * |
392 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
393 | * the generated function. |
394 | */ |
395 | #define SSAM_DEFINE_SYNC_REQUEST_W(name, atype, spec...) \ |
396 | static int name(struct ssam_controller *ctrl, const atype *arg) \ |
397 | { \ |
398 | struct ssam_request_spec s = (struct ssam_request_spec)spec; \ |
399 | struct ssam_request rqst; \ |
400 | \ |
401 | rqst.target_category = s.target_category; \ |
402 | rqst.target_id = s.target_id; \ |
403 | rqst.command_id = s.command_id; \ |
404 | rqst.instance_id = s.instance_id; \ |
405 | rqst.flags = s.flags; \ |
406 | rqst.length = sizeof(atype); \ |
407 | rqst.payload = (u8 *)arg; \ |
408 | \ |
409 | return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \ |
410 | sizeof(atype)); \ |
411 | } |
412 | |
413 | /** |
414 | * SSAM_DEFINE_SYNC_REQUEST_R() - Define synchronous SAM request function with |
415 | * return value. |
416 | * @name: Name of the generated function. |
417 | * @rtype: Type of the request's return value. |
418 | * @spec: Specification (&struct ssam_request_spec) defining the request. |
419 | * |
420 | * Defines a function executing the synchronous SAM request specified by |
421 | * @spec, with the request taking no argument but having a return value of |
422 | * type @rtype. The generated function takes care of setting up the request |
423 | * and response structs, buffer allocation, as well as execution of the |
424 | * request itself, returning once the request has been fully completed. The |
425 | * required transport buffer will be allocated on the stack. |
426 | * |
427 | * The generated function is defined as ``static int name(struct |
428 | * ssam_controller *ctrl, rtype *ret)``, returning the status of the request, |
429 | * which is zero on success and negative on failure. The ``ctrl`` parameter is |
430 | * the controller via which the request is sent. The request's return value is |
431 | * written to the memory pointed to by the ``ret`` parameter. |
432 | * |
433 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
434 | * the generated function. |
435 | */ |
436 | #define SSAM_DEFINE_SYNC_REQUEST_R(name, rtype, spec...) \ |
437 | static int name(struct ssam_controller *ctrl, rtype *ret) \ |
438 | { \ |
439 | struct ssam_request_spec s = (struct ssam_request_spec)spec; \ |
440 | struct ssam_request rqst; \ |
441 | struct ssam_response rsp; \ |
442 | int status; \ |
443 | \ |
444 | rqst.target_category = s.target_category; \ |
445 | rqst.target_id = s.target_id; \ |
446 | rqst.command_id = s.command_id; \ |
447 | rqst.instance_id = s.instance_id; \ |
448 | rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ |
449 | rqst.length = 0; \ |
450 | rqst.payload = NULL; \ |
451 | \ |
452 | rsp.capacity = sizeof(rtype); \ |
453 | rsp.length = 0; \ |
454 | rsp.pointer = (u8 *)ret; \ |
455 | \ |
456 | status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \ |
457 | if (status) \ |
458 | return status; \ |
459 | \ |
460 | if (rsp.length != sizeof(rtype)) { \ |
461 | struct device *dev = ssam_controller_device(ctrl); \ |
462 | dev_err(dev, \ |
463 | "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ |
464 | sizeof(rtype), rsp.length, rqst.target_category,\ |
465 | rqst.command_id); \ |
466 | return -EIO; \ |
467 | } \ |
468 | \ |
469 | return 0; \ |
470 | } |
471 | |
472 | /** |
473 | * SSAM_DEFINE_SYNC_REQUEST_WR() - Define synchronous SAM request function with |
474 | * both argument and return value. |
475 | * @name: Name of the generated function. |
476 | * @atype: Type of the request's argument. |
477 | * @rtype: Type of the request's return value. |
478 | * @spec: Specification (&struct ssam_request_spec) defining the request. |
479 | * |
480 | * Defines a function executing the synchronous SAM request specified by @spec, |
481 | * with the request taking an argument of type @atype and having a return value |
482 | * of type @rtype. The generated function takes care of setting up the request |
483 | * and response structs, buffer allocation, as well as execution of the request |
484 | * itself, returning once the request has been fully completed. The required |
485 | * transport buffer will be allocated on the stack. |
486 | * |
487 | * The generated function is defined as ``static int name(struct |
488 | * ssam_controller *ctrl, const atype *arg, rtype *ret)``, returning the status |
489 | * of the request, which is zero on success and negative on failure. The |
490 | * ``ctrl`` parameter is the controller via which the request is sent. The |
491 | * request argument is specified via the ``arg`` pointer. The request's return |
492 | * value is written to the memory pointed to by the ``ret`` parameter. |
493 | * |
494 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
495 | * the generated function. |
496 | */ |
497 | #define SSAM_DEFINE_SYNC_REQUEST_WR(name, atype, rtype, spec...) \ |
498 | static int name(struct ssam_controller *ctrl, const atype *arg, rtype *ret) \ |
499 | { \ |
500 | struct ssam_request_spec s = (struct ssam_request_spec)spec; \ |
501 | struct ssam_request rqst; \ |
502 | struct ssam_response rsp; \ |
503 | int status; \ |
504 | \ |
505 | rqst.target_category = s.target_category; \ |
506 | rqst.target_id = s.target_id; \ |
507 | rqst.command_id = s.command_id; \ |
508 | rqst.instance_id = s.instance_id; \ |
509 | rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ |
510 | rqst.length = sizeof(atype); \ |
511 | rqst.payload = (u8 *)arg; \ |
512 | \ |
513 | rsp.capacity = sizeof(rtype); \ |
514 | rsp.length = 0; \ |
515 | rsp.pointer = (u8 *)ret; \ |
516 | \ |
517 | status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \ |
518 | if (status) \ |
519 | return status; \ |
520 | \ |
521 | if (rsp.length != sizeof(rtype)) { \ |
522 | struct device *dev = ssam_controller_device(ctrl); \ |
523 | dev_err(dev, \ |
524 | "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ |
525 | sizeof(rtype), rsp.length, rqst.target_category,\ |
526 | rqst.command_id); \ |
527 | return -EIO; \ |
528 | } \ |
529 | \ |
530 | return 0; \ |
531 | } |
532 | |
533 | /** |
534 | * SSAM_DEFINE_SYNC_REQUEST_MD_N() - Define synchronous multi-device SAM |
535 | * request function with neither argument nor return value. |
536 | * @name: Name of the generated function. |
537 | * @spec: Specification (&struct ssam_request_spec_md) defining the request. |
538 | * |
539 | * Defines a function executing the synchronous SAM request specified by |
540 | * @spec, with the request having neither argument nor return value. Device |
541 | * specifying parameters are not hard-coded, but instead must be provided to |
542 | * the function. The generated function takes care of setting up the request |
543 | * struct, buffer allocation, as well as execution of the request itself, |
544 | * returning once the request has been fully completed. The required transport |
545 | * buffer will be allocated on the stack. |
546 | * |
547 | * The generated function is defined as ``static int name(struct |
548 | * ssam_controller *ctrl, u8 tid, u8 iid)``, returning the status of the |
549 | * request, which is zero on success and negative on failure. The ``ctrl`` |
550 | * parameter is the controller via which the request is sent, ``tid`` the |
551 | * target ID for the request, and ``iid`` the instance ID. |
552 | * |
553 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
554 | * the generated function. |
555 | */ |
556 | #define SSAM_DEFINE_SYNC_REQUEST_MD_N(name, spec...) \ |
557 | static int name(struct ssam_controller *ctrl, u8 tid, u8 iid) \ |
558 | { \ |
559 | struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ |
560 | struct ssam_request rqst; \ |
561 | \ |
562 | rqst.target_category = s.target_category; \ |
563 | rqst.target_id = tid; \ |
564 | rqst.command_id = s.command_id; \ |
565 | rqst.instance_id = iid; \ |
566 | rqst.flags = s.flags; \ |
567 | rqst.length = 0; \ |
568 | rqst.payload = NULL; \ |
569 | \ |
570 | return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0); \ |
571 | } |
572 | |
573 | /** |
574 | * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM |
575 | * request function with argument. |
576 | * @name: Name of the generated function. |
577 | * @atype: Type of the request's argument. |
578 | * @spec: Specification (&struct ssam_request_spec_md) defining the request. |
579 | * |
580 | * Defines a function executing the synchronous SAM request specified by |
581 | * @spec, with the request taking an argument of type @atype and having no |
582 | * return value. Device specifying parameters are not hard-coded, but instead |
583 | * must be provided to the function. The generated function takes care of |
584 | * setting up the request struct, buffer allocation, as well as execution of |
585 | * the request itself, returning once the request has been fully completed. |
586 | * The required transport buffer will be allocated on the stack. |
587 | * |
588 | * The generated function is defined as ``static int name(struct |
589 | * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)``, returning the |
590 | * status of the request, which is zero on success and negative on failure. |
591 | * The ``ctrl`` parameter is the controller via which the request is sent, |
592 | * ``tid`` the target ID for the request, and ``iid`` the instance ID. The |
593 | * request argument is specified via the ``arg`` pointer. |
594 | * |
595 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
596 | * the generated function. |
597 | */ |
598 | #define SSAM_DEFINE_SYNC_REQUEST_MD_W(name, atype, spec...) \ |
599 | static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg) \ |
600 | { \ |
601 | struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ |
602 | struct ssam_request rqst; \ |
603 | \ |
604 | rqst.target_category = s.target_category; \ |
605 | rqst.target_id = tid; \ |
606 | rqst.command_id = s.command_id; \ |
607 | rqst.instance_id = iid; \ |
608 | rqst.flags = s.flags; \ |
609 | rqst.length = sizeof(atype); \ |
610 | rqst.payload = (u8 *)arg; \ |
611 | \ |
612 | return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, \ |
613 | sizeof(atype)); \ |
614 | } |
615 | |
616 | /** |
617 | * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM |
618 | * request function with return value. |
619 | * @name: Name of the generated function. |
620 | * @rtype: Type of the request's return value. |
621 | * @spec: Specification (&struct ssam_request_spec_md) defining the request. |
622 | * |
623 | * Defines a function executing the synchronous SAM request specified by |
624 | * @spec, with the request taking no argument but having a return value of |
625 | * type @rtype. Device specifying parameters are not hard-coded, but instead |
626 | * must be provided to the function. The generated function takes care of |
627 | * setting up the request and response structs, buffer allocation, as well as |
628 | * execution of the request itself, returning once the request has been fully |
629 | * completed. The required transport buffer will be allocated on the stack. |
630 | * |
631 | * The generated function is defined as ``static int name(struct |
632 | * ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)``, returning the status |
633 | * of the request, which is zero on success and negative on failure. The |
634 | * ``ctrl`` parameter is the controller via which the request is sent, ``tid`` |
635 | * the target ID for the request, and ``iid`` the instance ID. The request's |
636 | * return value is written to the memory pointed to by the ``ret`` parameter. |
637 | * |
638 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
639 | * the generated function. |
640 | */ |
641 | #define SSAM_DEFINE_SYNC_REQUEST_MD_R(name, rtype, spec...) \ |
642 | static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret) \ |
643 | { \ |
644 | struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ |
645 | struct ssam_request rqst; \ |
646 | struct ssam_response rsp; \ |
647 | int status; \ |
648 | \ |
649 | rqst.target_category = s.target_category; \ |
650 | rqst.target_id = tid; \ |
651 | rqst.command_id = s.command_id; \ |
652 | rqst.instance_id = iid; \ |
653 | rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ |
654 | rqst.length = 0; \ |
655 | rqst.payload = NULL; \ |
656 | \ |
657 | rsp.capacity = sizeof(rtype); \ |
658 | rsp.length = 0; \ |
659 | rsp.pointer = (u8 *)ret; \ |
660 | \ |
661 | status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0); \ |
662 | if (status) \ |
663 | return status; \ |
664 | \ |
665 | if (rsp.length != sizeof(rtype)) { \ |
666 | struct device *dev = ssam_controller_device(ctrl); \ |
667 | dev_err(dev, \ |
668 | "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ |
669 | sizeof(rtype), rsp.length, rqst.target_category,\ |
670 | rqst.command_id); \ |
671 | return -EIO; \ |
672 | } \ |
673 | \ |
674 | return 0; \ |
675 | } |
676 | |
677 | /** |
678 | * SSAM_DEFINE_SYNC_REQUEST_MD_WR() - Define synchronous multi-device SAM |
679 | * request function with both argument and return value. |
680 | * @name: Name of the generated function. |
681 | * @atype: Type of the request's argument. |
682 | * @rtype: Type of the request's return value. |
683 | * @spec: Specification (&struct ssam_request_spec_md) defining the request. |
684 | * |
685 | * Defines a function executing the synchronous SAM request specified by @spec, |
686 | * with the request taking an argument of type @atype and having a return value |
687 | * of type @rtype. Device specifying parameters are not hard-coded, but instead |
688 | * must be provided to the function. The generated function takes care of |
689 | * setting up the request and response structs, buffer allocation, as well as |
690 | * execution of the request itself, returning once the request has been fully |
691 | * completed. The required transport buffer will be allocated on the stack. |
692 | * |
693 | * The generated function is defined as ``static int name(struct |
694 | * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg, rtype *ret)``, |
695 | * returning the status of the request, which is zero on success and negative |
696 | * on failure. The ``ctrl`` parameter is the controller via which the request |
697 | * is sent, ``tid`` the target ID for the request, and ``iid`` the instance ID. |
698 | * The request argument is specified via the ``arg`` pointer. The request's |
699 | * return value is written to the memory pointed to by the ``ret`` parameter. |
700 | * |
701 | * Refer to ssam_request_do_sync_onstack() for more details on the behavior of |
702 | * the generated function. |
703 | */ |
704 | #define SSAM_DEFINE_SYNC_REQUEST_MD_WR(name, atype, rtype, spec...) \ |
705 | static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, \ |
706 | const atype *arg, rtype *ret) \ |
707 | { \ |
708 | struct ssam_request_spec_md s = (struct ssam_request_spec_md)spec; \ |
709 | struct ssam_request rqst; \ |
710 | struct ssam_response rsp; \ |
711 | int status; \ |
712 | \ |
713 | rqst.target_category = s.target_category; \ |
714 | rqst.target_id = tid; \ |
715 | rqst.command_id = s.command_id; \ |
716 | rqst.instance_id = iid; \ |
717 | rqst.flags = s.flags | SSAM_REQUEST_HAS_RESPONSE; \ |
718 | rqst.length = sizeof(atype); \ |
719 | rqst.payload = (u8 *)arg; \ |
720 | \ |
721 | rsp.capacity = sizeof(rtype); \ |
722 | rsp.length = 0; \ |
723 | rsp.pointer = (u8 *)ret; \ |
724 | \ |
725 | status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \ |
726 | if (status) \ |
727 | return status; \ |
728 | \ |
729 | if (rsp.length != sizeof(rtype)) { \ |
730 | struct device *dev = ssam_controller_device(ctrl); \ |
731 | dev_err(dev, \ |
732 | "rqst: invalid response length, expected %zu, got %zu (tc: %#04x, cid: %#04x)", \ |
733 | sizeof(rtype), rsp.length, rqst.target_category,\ |
734 | rqst.command_id); \ |
735 | return -EIO; \ |
736 | } \ |
737 | \ |
738 | return 0; \ |
739 | } |
740 | |
741 | |
742 | /* -- Event notifier/callbacks. --------------------------------------------- */ |
743 | |
744 | #define SSAM_NOTIF_STATE_SHIFT 2 |
745 | #define SSAM_NOTIF_STATE_MASK ((1 << SSAM_NOTIF_STATE_SHIFT) - 1) |
746 | |
747 | /** |
748 | * enum ssam_notif_flags - Flags used in return values from SSAM notifier |
749 | * callback functions. |
750 | * |
751 | * @SSAM_NOTIF_HANDLED: |
752 | * Indicates that the notification has been handled. This flag should be |
753 | * set by the handler if the handler can act/has acted upon the event |
754 | * provided to it. This flag should not be set if the handler is not a |
755 | * primary handler intended for the provided event. |
756 | * |
757 | * If this flag has not been set by any handler after the notifier chain |
758 | * has been traversed, a warning will be emitted, stating that the event |
759 | * has not been handled. |
760 | * |
761 | * @SSAM_NOTIF_STOP: |
762 | * Indicates that the notifier traversal should stop. If this flag is |
763 | * returned from a notifier callback, notifier chain traversal will |
764 | * immediately stop and any remaining notifiers will not be called. This |
765 | * flag is automatically set when ssam_notifier_from_errno() is called |
766 | * with a negative error value. |
767 | */ |
768 | enum ssam_notif_flags { |
769 | SSAM_NOTIF_HANDLED = BIT(0), |
770 | SSAM_NOTIF_STOP = BIT(1), |
771 | }; |
772 | |
773 | struct ssam_event_notifier; |
774 | |
775 | typedef u32 (*ssam_notifier_fn_t)(struct ssam_event_notifier *nf, |
776 | const struct ssam_event *event); |
777 | |
778 | /** |
779 | * struct ssam_notifier_block - Base notifier block for SSAM event |
780 | * notifications. |
781 | * @node: The node for the list of notifiers. |
782 | * @fn: The callback function of this notifier. This function takes the |
783 | * respective notifier block and event as input and should return |
784 | * a notifier value, which can either be obtained from the flags |
785 | * provided in &enum ssam_notif_flags, converted from a standard |
786 | * error value via ssam_notifier_from_errno(), or a combination of |
787 | * both (e.g. ``ssam_notifier_from_errno(e) | SSAM_NOTIF_HANDLED``). |
788 | * @priority: Priority value determining the order in which notifier callbacks |
789 | * will be called. A higher value means higher priority, i.e. the |
790 | * associated callback will be executed earlier than other (lower |
791 | * priority) callbacks. |
792 | */ |
793 | struct ssam_notifier_block { |
794 | struct list_head node; |
795 | ssam_notifier_fn_t fn; |
796 | int priority; |
797 | }; |
798 | |
799 | /** |
800 | * ssam_notifier_from_errno() - Convert standard error value to notifier |
801 | * return code. |
802 | * @err: The error code to convert, must be negative (in case of failure) or |
803 | * zero (in case of success). |
804 | * |
805 | * Return: Returns the notifier return value obtained by converting the |
806 | * specified @err value. In case @err is negative, the %SSAM_NOTIF_STOP flag |
807 | * will be set, causing notifier call chain traversal to abort. |
808 | */ |
809 | static inline u32 ssam_notifier_from_errno(int err) |
810 | { |
811 | if (WARN_ON(err > 0) || err == 0) |
812 | return 0; |
813 | else |
814 | return ((-err) << SSAM_NOTIF_STATE_SHIFT) | SSAM_NOTIF_STOP; |
815 | } |
816 | |
817 | /** |
818 | * ssam_notifier_to_errno() - Convert notifier return code to standard error |
819 | * value. |
820 | * @ret: The notifier return value to convert. |
821 | * |
822 | * Return: Returns the negative error value encoded in @ret or zero if @ret |
823 | * indicates success. |
824 | */ |
825 | static inline int ssam_notifier_to_errno(u32 ret) |
826 | { |
827 | return -(ret >> SSAM_NOTIF_STATE_SHIFT); |
828 | } |
829 | |
830 | |
831 | /* -- Event/notification registry. ------------------------------------------ */ |
832 | |
833 | /** |
834 | * struct ssam_event_registry - Registry specification used for enabling events. |
835 | * @target_category: Target category for the event registry requests. |
836 | * @target_id: Target ID for the event registry requests. |
837 | * @cid_enable: Command ID for the event-enable request. |
838 | * @cid_disable: Command ID for the event-disable request. |
839 | * |
840 | * This struct describes a SAM event registry via the minimal collection of |
841 | * SAM IDs specifying the requests to use for enabling and disabling an event. |
842 | * The individual event to be enabled/disabled itself is specified via &struct |
843 | * ssam_event_id. |
844 | */ |
845 | struct ssam_event_registry { |
846 | u8 target_category; |
847 | u8 target_id; |
848 | u8 cid_enable; |
849 | u8 cid_disable; |
850 | }; |
851 | |
852 | /** |
853 | * struct ssam_event_id - Unique event ID used for enabling events. |
854 | * @target_category: Target category of the event source. |
855 | * @instance: Instance ID of the event source. |
856 | * |
857 | * This struct specifies the event to be enabled/disabled via an externally |
858 | * provided registry. It does not specify the registry to be used itself, this |
859 | * is done via &struct ssam_event_registry. |
860 | */ |
861 | struct ssam_event_id { |
862 | u8 target_category; |
863 | u8 instance; |
864 | }; |
865 | |
866 | /** |
867 | * enum ssam_event_mask - Flags specifying how events are matched to notifiers. |
868 | * |
869 | * @SSAM_EVENT_MASK_NONE: |
870 | * Run the callback for any event with matching target category. Do not |
871 | * do any additional filtering. |
872 | * |
873 | * @SSAM_EVENT_MASK_TARGET: |
874 | * In addition to filtering by target category, only execute the notifier |
875 | * callback for events with a target ID matching to the one of the |
876 | * registry used for enabling/disabling the event. |
877 | * |
878 | * @SSAM_EVENT_MASK_INSTANCE: |
879 | * In addition to filtering by target category, only execute the notifier |
880 | * callback for events with an instance ID matching to the instance ID |
881 | * used when enabling the event. |
882 | * |
883 | * @SSAM_EVENT_MASK_STRICT: |
884 | * Do all the filtering above. |
885 | */ |
886 | enum ssam_event_mask { |
887 | SSAM_EVENT_MASK_TARGET = BIT(0), |
888 | SSAM_EVENT_MASK_INSTANCE = BIT(1), |
889 | |
890 | SSAM_EVENT_MASK_NONE = 0, |
891 | SSAM_EVENT_MASK_STRICT = |
892 | SSAM_EVENT_MASK_TARGET |
893 | | SSAM_EVENT_MASK_INSTANCE, |
894 | }; |
895 | |
896 | /** |
897 | * SSAM_EVENT_REGISTRY() - Define a new event registry. |
898 | * @tc: Target category for the event registry requests. |
899 | * @tid: Target ID for the event registry requests. |
900 | * @cid_en: Command ID for the event-enable request. |
901 | * @cid_dis: Command ID for the event-disable request. |
902 | * |
903 | * Return: Returns the &struct ssam_event_registry specified by the given |
904 | * parameters. |
905 | */ |
906 | #define SSAM_EVENT_REGISTRY(tc, tid, cid_en, cid_dis) \ |
907 | ((struct ssam_event_registry) { \ |
908 | .target_category = (tc), \ |
909 | .target_id = (tid), \ |
910 | .cid_enable = (cid_en), \ |
911 | .cid_disable = (cid_dis), \ |
912 | }) |
913 | |
914 | #define SSAM_EVENT_REGISTRY_SAM \ |
915 | SSAM_EVENT_REGISTRY(SSAM_SSH_TC_SAM, SSAM_SSH_TID_SAM, 0x0b, 0x0c) |
916 | |
917 | #define SSAM_EVENT_REGISTRY_KIP \ |
918 | SSAM_EVENT_REGISTRY(SSAM_SSH_TC_KIP, SSAM_SSH_TID_KIP, 0x27, 0x28) |
919 | |
920 | #define SSAM_EVENT_REGISTRY_REG(tid)\ |
921 | SSAM_EVENT_REGISTRY(SSAM_SSH_TC_REG, tid, 0x01, 0x02) |
922 | |
923 | /** |
924 | * enum ssam_event_notifier_flags - Flags for event notifiers. |
925 | * @SSAM_EVENT_NOTIFIER_OBSERVER: |
926 | * The corresponding notifier acts as observer. Registering a notifier |
927 | * with this flag set will not attempt to enable any event. Equally, |
928 | * unregistering will not attempt to disable any event. Note that a |
929 | * notifier with this flag may not even correspond to a certain event at |
930 | * all, only to a specific event target category. Event matching will not |
931 | * be influenced by this flag. |
932 | */ |
933 | enum ssam_event_notifier_flags { |
934 | SSAM_EVENT_NOTIFIER_OBSERVER = BIT(0), |
935 | }; |
936 | |
937 | /** |
938 | * struct ssam_event_notifier - Notifier block for SSAM events. |
939 | * @base: The base notifier block with callback function and priority. |
940 | * @event: The event for which this block will receive notifications. |
941 | * @event.reg: Registry via which the event will be enabled/disabled. |
942 | * @event.id: ID specifying the event. |
943 | * @event.mask: Flags determining how events are matched to the notifier. |
944 | * @event.flags: Flags used for enabling the event. |
945 | * @flags: Notifier flags (see &enum ssam_event_notifier_flags). |
946 | */ |
947 | struct ssam_event_notifier { |
948 | struct ssam_notifier_block base; |
949 | |
950 | struct { |
951 | struct ssam_event_registry reg; |
952 | struct ssam_event_id id; |
953 | enum ssam_event_mask mask; |
954 | u8 flags; |
955 | } event; |
956 | |
957 | unsigned long flags; |
958 | }; |
959 | |
960 | int ssam_notifier_register(struct ssam_controller *ctrl, |
961 | struct ssam_event_notifier *n); |
962 | |
963 | int __ssam_notifier_unregister(struct ssam_controller *ctrl, |
964 | struct ssam_event_notifier *n, bool disable); |
965 | |
966 | /** |
967 | * ssam_notifier_unregister() - Unregister an event notifier. |
968 | * @ctrl: The controller the notifier has been registered on. |
969 | * @n: The event notifier to unregister. |
970 | * |
971 | * Unregister an event notifier. Decrement the usage counter of the associated |
972 | * SAM event if the notifier is not marked as an observer. If the usage counter |
973 | * reaches zero, the event will be disabled. |
974 | * |
975 | * Return: Returns zero on success, %-ENOENT if the given notifier block has |
976 | * not been registered on the controller. If the given notifier block was the |
977 | * last one associated with its specific event, returns the status of the |
978 | * event-disable EC-command. |
979 | */ |
980 | static inline int ssam_notifier_unregister(struct ssam_controller *ctrl, |
981 | struct ssam_event_notifier *n) |
982 | { |
983 | return __ssam_notifier_unregister(ctrl, n, disable: true); |
984 | } |
985 | |
986 | int ssam_controller_event_enable(struct ssam_controller *ctrl, |
987 | struct ssam_event_registry reg, |
988 | struct ssam_event_id id, u8 flags); |
989 | |
990 | int ssam_controller_event_disable(struct ssam_controller *ctrl, |
991 | struct ssam_event_registry reg, |
992 | struct ssam_event_id id, u8 flags); |
993 | |
994 | #endif /* _LINUX_SURFACE_AGGREGATOR_CONTROLLER_H */ |
995 | |