linux/surface_aggregator/controller.h

1 /* SPDX-License-Identifier: GPL-2.0+ */
9  * Copyright (C) 2019-2021 Maximilian Luz <luzmaximilian@gmail.com>
22 /* -- Main data types and definitions --------------------------------------- */
25  * enum ssam_event_flags - Flags for enabling/disabling SAM events
33  * struct ssam_event - SAM event sent from the EC to the host.
51  * enum ssam_request_flags - Flags for SAM requests.
70  * struct ssam_request - SAM request description.
94  * struct ssam_response - Response buffer for SAM request.
110 int ssam_client_link(struct ssam_controller *ctrl, struct device *client);
121 				struct ssam_controller *ctrl,
125 /* -- Synchronous request interface. ---------------------------------------- */
128  * struct ssam_request_sync - Synchronous SAM request struct.
155  * ssam_request_sync_set_data - Set message data of a synchronous request.
166 	ssh_request_set_data(&rqst->base, ptr, len);  in ssam_request_sync_set_data()
170  * ssam_request_sync_set_resp - Set response buffer of a synchronous request.
181 	rqst->resp = resp;  in ssam_request_sync_set_resp()
184 int ssam_request_sync_submit(struct ssam_controller *ctrl,
188  * ssam_request_sync_wait - Wait for completion of a synchronous request.
206 	wait_for_completion(&rqst->comp);  in ssam_request_sync_wait()
207 	return rqst->status;  in ssam_request_sync_wait()
210 int ssam_request_do_sync(struct ssam_controller *ctrl,
214 int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,
220  * ssam_request_do_sync_onstack - Execute a synchronous request on the stack.
221  * @ctrl: The controller via which the request is submitted.
238 #define ssam_request_do_sync_onstack(ctrl, rqst, rsp, payload_len)		\  argument
243 		ssam_request_do_sync_with_buffer(ctrl, rqst, rsp, &__buf);	\
247  * __ssam_retry - Retry request in case of I/O errors or timeouts.
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
263 		for (__i = (n); __i > 0; __i--) {			\
265 			if (__s != -ETIMEDOUT && __s != -EREMOTEIO)	\
272  * ssam_retry - Retry request in case of I/O errors or timeouts up to three
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
290  * struct ssam_request_spec - Blue-print specification of SAM request.
297  * Blue-print specification for a SAM request. This struct describes the
299  * its instance-specific data (e.g. payload). It is intended to be used as base
312  * struct ssam_request_spec_md - Blue-print specification for multi-device SAM
318  * Blue-print specification for a multi-device SAM request, i.e. a request
320  * individual target and instance IDs. This struct describes the unique static
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
335  * SSAM_DEFINE_SYNC_REQUEST_N() - Define synchronous SAM request function
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
356 	static int name(struct ssam_controller *ctrl)				\
369 		return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0);	\
373  * SSAM_DEFINE_SYNC_REQUEST_W() - Define synchronous SAM request function with
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``
396 	static int name(struct ssam_controller *ctrl, const atype *arg)		\
409 		return ssam_request_do_sync_onstack(ctrl, &rqst, NULL,		\
414  * SSAM_DEFINE_SYNC_REQUEST_R() - Define synchronous SAM request function with
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
437 	static int name(struct ssam_controller *ctrl, rtype *ret)		\
456 		status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0);	\
461 			struct device *dev = ssam_controller_device(ctrl);	\
466 			return -EIO;						\
473  * SSAM_DEFINE_SYNC_REQUEST_WR() - Define synchronous SAM request function with
488  * ssam_controller *ctrl, const atype *arg, rtype *ret)``, returning the status
490  * ``ctrl`` parameter is the controller via which the request is sent. The
498 	static int name(struct ssam_controller *ctrl, const atype *arg, rtype *ret) \
517 		status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
522 			struct device *dev = ssam_controller_device(ctrl);	\
527 			return -EIO;						\
534  * SSAM_DEFINE_SYNC_REQUEST_MD_N() - Define synchronous multi-device SAM
541  * specifying parameters are not hard-coded, but instead must be provided to
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``
557 	static int name(struct ssam_controller *ctrl, u8 tid, u8 iid)		\
570 		return ssam_request_do_sync_onstack(ctrl, &rqst, NULL, 0);	\
574  * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM
582  * return value. Device specifying parameters are not hard-coded, but instead
589  * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg)``, returning the
591  * The ``ctrl`` parameter is the controller via which the request is sent,
599 	static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg) \
612 		return ssam_request_do_sync_onstack(ctrl, &rqst, NULL,		\
617  * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM
625  * type @rtype. Device specifying parameters are not hard-coded, but instead
632  * ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret)``, returning the status
634  * ``ctrl`` parameter is the controller via which the request is sent, ``tid``
642 	static int name(struct ssam_controller *ctrl, u8 tid, u8 iid, rtype *ret) \
661 		status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, 0);	\
666 			struct device *dev = ssam_controller_device(ctrl);	\
671 			return -EIO;						\
678  * SSAM_DEFINE_SYNC_REQUEST_MD_WR() - Define synchronous multi-device SAM
687  * of type @rtype. Device specifying parameters are not hard-coded, but instead
694  * ssam_controller *ctrl, u8 tid, u8 iid, const atype *arg, rtype *ret)``,
696  * on failure. The ``ctrl`` parameter is the controller via which the request
705 	static int name(struct ssam_controller *ctrl, u8 tid, u8 iid,		\
725 		status = ssam_request_do_sync_onstack(ctrl, &rqst, &rsp, sizeof(atype)); \
730 			struct device *dev = ssam_controller_device(ctrl);	\
735 			return -EIO;						\
742 /* -- Event notifier/callbacks. --------------------------------------------- */
745 #define SSAM_NOTIF_STATE_MASK		((1 << SSAM_NOTIF_STATE_SHIFT) - 1)
748  * enum ssam_notif_flags - Flags used in return values from SSAM notifier
779  * struct ssam_notifier_block - Base notifier block for SSAM event
800  * ssam_notifier_from_errno() - Convert standard error value to notifier
814 		return ((-err) << SSAM_NOTIF_STATE_SHIFT) | SSAM_NOTIF_STOP;  in ssam_notifier_from_errno()
818  * ssam_notifier_to_errno() - Convert notifier return code to standard error
827 	return -(ret >> SSAM_NOTIF_STATE_SHIFT);  in ssam_notifier_to_errno()
831 /* -- Event/notification registry. ------------------------------------------ */
834  * struct ssam_event_registry - Registry specification used for enabling events.
837  * @cid_enable:      Command ID for the event-enable request.
838  * @cid_disable:     Command ID for the event-disable request.
841  * SAM IDs specifying the requests to use for enabling and disabling an event.
853  * struct ssam_event_id - Unique event ID used for enabling events.
867  * enum ssam_event_mask - Flags specifying how events are matched to notifiers.
897  * SSAM_EVENT_REGISTRY() - Define a new event registry.
900  * @cid_en:  Command ID for the event-enable request.
901  * @cid_dis: Command ID for the event-disable request.
924  * enum ssam_event_notifier_flags - Flags for event notifiers.
938  * struct ssam_event_notifier - Notifier block for SSAM events.
960 int ssam_notifier_register(struct ssam_controller *ctrl,
963 int __ssam_notifier_unregister(struct ssam_controller *ctrl,
967  * ssam_notifier_unregister() - Unregister an event notifier.
968  * @ctrl:    The controller the notifier has been registered on.
975  * Return: Returns zero on success, %-ENOENT if the given notifier block has
978  * event-disable EC-command.
980 static inline int ssam_notifier_unregister(struct ssam_controller *ctrl,  in ssam_notifier_unregister()  argument
983 	return __ssam_notifier_unregister(ctrl, n, true);  in ssam_notifier_unregister()
986 int ssam_controller_event_enable(struct ssam_controller *ctrl,
990 int ssam_controller_event_disable(struct ssam_controller *ctrl,