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.
37  * @instance_id:     Instance ID of the event source.
51  * enum ssam_request_flags - Flags for SAM requests.
70  * struct ssam_request - SAM request description.
74  * @instance_id:     Instance ID of the request's target.
94  * struct ssam_response - Response buffer for SAM request.
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()
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()
220  * ssam_request_do_sync_onstack - Execute a synchronous request on the stack.
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.
294  * @instance_id:     Instance ID of the request's target.
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
373  * SSAM_DEFINE_SYNC_REQUEST_W() - Define synchronous SAM request function with
414  * SSAM_DEFINE_SYNC_REQUEST_R() - Define synchronous SAM request function with
466 			return -EIO;						\
473  * SSAM_DEFINE_SYNC_REQUEST_WR() - Define synchronous SAM request function with
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
551  * target ID for the request, and ``iid`` the instance ID.
574  * SSAM_DEFINE_SYNC_REQUEST_MD_W() - Define synchronous multi-device SAM
582  * return value. Device specifying parameters are not hard-coded, but instead
592  * ``tid`` the target ID for the request, and ``iid`` the instance ID. The
617  * SSAM_DEFINE_SYNC_REQUEST_MD_R() - Define synchronous multi-device SAM
625  * type @rtype. Device specifying parameters are not hard-coded, but instead
635  * the target ID for the request, and ``iid`` the instance ID. The request's
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
697  * is sent, ``tid`` the target ID for the request, and ``iid`` the instance ID.
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.
853  * struct ssam_event_id - Unique event ID used for enabling events.
855  * @instance:        Instance ID of the event source.
863 	u8 instance;  member
867  * enum ssam_event_mask - Flags specifying how events are matched to notifiers.
880  *	callback for events with an instance ID matching to the instance ID
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.
967  * ssam_notifier_unregister() - Unregister an event notifier.
975  * Return: Returns zero on success, %-ENOENT if the given notifier block has
978  * event-disable EC-command.