controller.h

  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 */
 28enum 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 */
 41struct 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 */
 64enum 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 */
 83struct 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 */
100struct ssam_response {
101	size_t capacity;
102	size_t length;
103	u8 *pointer;
104};
105
106struct ssam_controller;
107
108struct ssam_controller *ssam_get_controller(void);
109struct ssam_controller *ssam_client_bind(struct device *client);
110int ssam_client_link(struct ssam_controller *ctrl, struct device *client);
111
112struct device *ssam_controller_device(struct ssam_controller *c);
113
114struct ssam_controller *ssam_controller_get(struct ssam_controller *c);
115void ssam_controller_put(struct ssam_controller *c);
116
117void ssam_controller_statelock(struct ssam_controller *c);
118void ssam_controller_stateunlock(struct ssam_controller *c);
119
120ssize_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 */
138struct ssam_request_sync {
139	struct ssh_request base;
140	struct completion comp;
141	struct ssam_response *resp;
142	int status;
143};
144
145int ssam_request_sync_alloc(size_t payload_len, gfp_t flags,
146			    struct ssam_request_sync **rqst,
147			    struct ssam_span *buffer);
148
149void ssam_request_sync_free(struct ssam_request_sync *rqst);
150
151int 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 */
163static 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 */
178static inline void ssam_request_sync_set_resp(struct ssam_request_sync *rqst,
179					      struct ssam_response *resp)
180{
181	rqst->resp = resp;
182}
183
184int 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 */
204static inline int ssam_request_sync_wait(struct ssam_request_sync *rqst)
205{
206	wait_for_completion(&rqst->comp);
207	return rqst->status;
208}
209
210int ssam_request_do_sync(struct ssam_controller *ctrl,
211			 const struct ssam_request *spec,
212			 struct ssam_response *rsp);
213
214int 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 */
303struct 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 */
328struct 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 */
768enum ssam_notif_flags {
769	SSAM_NOTIF_HANDLED = BIT(0),
770	SSAM_NOTIF_STOP    = BIT(1),
771};
772
773struct ssam_event_notifier;
774
775typedef 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 */
793struct 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 */
809static 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 */
825static 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 */
845struct 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 */
861struct 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 */
886enum 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 */
933enum 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 */
947struct 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
960int ssam_notifier_register(struct ssam_controller *ctrl,
961			   struct ssam_event_notifier *n);
962
963int __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 */
980static 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
986int ssam_controller_event_enable(struct ssam_controller *ctrl,
987				 struct ssam_event_registry reg,
988				 struct ssam_event_id id, u8 flags);
989
990int 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 */