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[];
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  */
ssam_request_sync_set_data(struct ssam_request_sync * rqst,u8 * ptr,size_t len)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(&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  */
ssam_request_sync_set_resp(struct ssam_request_sync * rqst,struct ssam_response * resp)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  */
ssam_request_sync_wait(struct ssam_request_sync * rqst)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  */
ssam_notifier_from_errno(int err)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  */
ssam_notifier_to_errno(u32 ret)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  */
ssam_notifier_unregister(struct ssam_controller * ctrl,struct ssam_event_notifier * n)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, 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