// SPDX-License-Identifier: GPL-2.0+ /* * Main SSAM/SSH controller structure and functionality. * * Copyright (C) 2019-2022 Maximilian Luz <[email protected]> */ #include <linux/acpi.h> #include <linux/atomic.h> #include <linux/completion.h> #include <linux/gpio/consumer.h> #include <linux/interrupt.h> #include <linux/kref.h> #include <linux/limits.h> #include <linux/list.h> #include <linux/lockdep.h> #include <linux/mutex.h> #include <linux/rculist.h> #include <linux/rbtree.h> #include <linux/rwsem.h> #include <linux/serdev.h> #include <linux/slab.h> #include <linux/spinlock.h> #include <linux/srcu.h> #include <linux/types.h> #include <linux/workqueue.h> #include <linux/surface_aggregator/controller.h> #include <linux/surface_aggregator/serial_hub.h> #include "controller.h" #include "ssh_msgb.h" #include "ssh_request_layer.h" #include "trace.h" /* -- Safe counters. -------------------------------------------------------- */ /** * ssh_seq_reset() - Reset/initialize sequence ID counter. * @c: The counter to reset. */ static void ssh_seq_reset(struct ssh_seq_counter *c) { … } /** * ssh_seq_next() - Get next sequence ID. * @c: The counter providing the sequence IDs. * * Return: Returns the next sequence ID of the counter. */ static u8 ssh_seq_next(struct ssh_seq_counter *c) { … } /** * ssh_rqid_reset() - Reset/initialize request ID counter. * @c: The counter to reset. */ static void ssh_rqid_reset(struct ssh_rqid_counter *c) { … } /** * ssh_rqid_next() - Get next request ID. * @c: The counter providing the request IDs. * * Return: Returns the next request ID of the counter, skipping any reserved * request IDs. */ static u16 ssh_rqid_next(struct ssh_rqid_counter *c) { … } /* -- Event notifier/callbacks. --------------------------------------------- */ /* * The notifier system is based on linux/notifier.h, specifically the SRCU * implementation. The difference to that is, that some bits of the notifier * call return value can be tracked across multiple calls. This is done so * that handling of events can be tracked and a warning can be issued in case * an event goes unhandled. The idea of that warning is that it should help * discover and identify new/currently unimplemented features. */ /** * ssam_event_matches_notifier() - Test if an event matches a notifier. * @n: The event notifier to test against. * @event: The event to test. * * Return: Returns %true if the given event matches the given notifier * according to the rules set in the notifier's event mask, %false otherwise. */ static bool ssam_event_matches_notifier(const struct ssam_event_notifier *n, const struct ssam_event *event) { … } /** * ssam_nfblk_call_chain() - Call event notifier callbacks of the given chain. * @nh: The notifier head for which the notifier callbacks should be called. * @event: The event data provided to the callbacks. * * Call all registered notifier callbacks in order of their priority until * either no notifier is left or a notifier returns a value with the * %SSAM_NOTIF_STOP bit set. Note that this bit is automatically set via * ssam_notifier_from_errno() on any non-zero error value. * * Return: Returns the notifier status value, which contains the notifier * status bits (%SSAM_NOTIF_HANDLED and %SSAM_NOTIF_STOP) as well as a * potential error value returned from the last executed notifier callback. * Use ssam_notifier_to_errno() to convert this value to the original error * value. */ static int ssam_nfblk_call_chain(struct ssam_nf_head *nh, struct ssam_event *event) { … } /** * ssam_nfblk_insert() - Insert a new notifier block into the given notifier * list. * @nh: The notifier head into which the block should be inserted. * @nb: The notifier block to add. * * Note: This function must be synchronized by the caller with respect to other * insert, find, and/or remove calls by holding ``struct ssam_nf.lock``. * * Return: Returns zero on success, %-EEXIST if the notifier block has already * been registered. */ static int ssam_nfblk_insert(struct ssam_nf_head *nh, struct ssam_notifier_block *nb) { … } /** * ssam_nfblk_find() - Check if a notifier block is registered on the given * notifier head. * list. * @nh: The notifier head on which to search. * @nb: The notifier block to search for. * * Note: This function must be synchronized by the caller with respect to other * insert, find, and/or remove calls by holding ``struct ssam_nf.lock``. * * Return: Returns true if the given notifier block is registered on the given * notifier head, false otherwise. */ static bool ssam_nfblk_find(struct ssam_nf_head *nh, struct ssam_notifier_block *nb) { … } /** * ssam_nfblk_remove() - Remove a notifier block from its notifier list. * @nb: The notifier block to be removed. * * Note: This function must be synchronized by the caller with respect to * other insert, find, and/or remove calls by holding ``struct ssam_nf.lock``. * Furthermore, the caller _must_ ensure SRCU synchronization by calling * synchronize_srcu() with ``nh->srcu`` after leaving the critical section, to * ensure that the removed notifier block is not in use any more. */ static void ssam_nfblk_remove(struct ssam_notifier_block *nb) { … } /** * ssam_nf_head_init() - Initialize the given notifier head. * @nh: The notifier head to initialize. */ static int ssam_nf_head_init(struct ssam_nf_head *nh) { … } /** * ssam_nf_head_destroy() - Deinitialize the given notifier head. * @nh: The notifier head to deinitialize. */ static void ssam_nf_head_destroy(struct ssam_nf_head *nh) { … } /* -- Event/notification registry. ------------------------------------------ */ /** * struct ssam_nf_refcount_key - Key used for event activation reference * counting. * @reg: The registry via which the event is enabled/disabled. * @id: The ID uniquely describing the event. */ struct ssam_nf_refcount_key { … }; /** * struct ssam_nf_refcount_entry - RB-tree entry for reference counting event * activations. * @node: The node of this entry in the rb-tree. * @key: The key of the event. * @refcount: The reference-count of the event. * @flags: The flags used when enabling the event. */ struct ssam_nf_refcount_entry { … }; /** * ssam_nf_refcount_inc() - Increment reference-/activation-count of the given * event. * @nf: The notifier system reference. * @reg: The registry used to enable/disable the event. * @id: The event ID. * * Increments the reference-/activation-count associated with the specified * event type/ID, allocating a new entry for this event ID if necessary. A * newly allocated entry will have a refcount of one. * * Note: ``nf->lock`` must be held when calling this function. * * Return: Returns the refcount entry on success. Returns an error pointer * with %-ENOSPC if there have already been %INT_MAX events of the specified * ID and type registered, or %-ENOMEM if the entry could not be allocated. */ static struct ssam_nf_refcount_entry * ssam_nf_refcount_inc(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id) { … } /** * ssam_nf_refcount_dec() - Decrement reference-/activation-count of the given * event. * @nf: The notifier system reference. * @reg: The registry used to enable/disable the event. * @id: The event ID. * * Decrements the reference-/activation-count of the specified event, * returning its entry. If the returned entry has a refcount of zero, the * caller is responsible for freeing it using kfree(). * * Note: ``nf->lock`` must be held when calling this function. * * Return: Returns the refcount entry on success or %NULL if the entry has not * been found. */ static struct ssam_nf_refcount_entry * ssam_nf_refcount_dec(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id) { … } /** * ssam_nf_refcount_dec_free() - Decrement reference-/activation-count of the * given event and free its entry if the reference count reaches zero. * @nf: The notifier system reference. * @reg: The registry used to enable/disable the event. * @id: The event ID. * * Decrements the reference-/activation-count of the specified event, freeing * its entry if it reaches zero. * * Note: ``nf->lock`` must be held when calling this function. */ static void ssam_nf_refcount_dec_free(struct ssam_nf *nf, struct ssam_event_registry reg, struct ssam_event_id id) { … } /** * ssam_nf_refcount_empty() - Test if the notification system has any * enabled/active events. * @nf: The notification system. */ static bool ssam_nf_refcount_empty(struct ssam_nf *nf) { … } /** * ssam_nf_call() - Call notification callbacks for the provided event. * @nf: The notifier system * @dev: The associated device, only used for logging. * @rqid: The request ID of the event. * @event: The event provided to the callbacks. * * Execute registered callbacks in order of their priority until either no * callback is left or a callback returns a value with the %SSAM_NOTIF_STOP * bit set. Note that this bit is set automatically when converting non-zero * error values via ssam_notifier_from_errno() to notifier values. * * Also note that any callback that could handle an event should return a value * with bit %SSAM_NOTIF_HANDLED set, indicating that the event does not go * unhandled/ignored. In case no registered callback could handle an event, * this function will emit a warning. * * In case a callback failed, this function will emit an error message. */ static void ssam_nf_call(struct ssam_nf *nf, struct device *dev, u16 rqid, struct ssam_event *event) { … } /** * ssam_nf_init() - Initialize the notifier system. * @nf: The notifier system to initialize. */ static int ssam_nf_init(struct ssam_nf *nf) { … } /** * ssam_nf_destroy() - Deinitialize the notifier system. * @nf: The notifier system to deinitialize. */ static void ssam_nf_destroy(struct ssam_nf *nf) { … } /* -- Event/async request completion system. -------------------------------- */ #define SSAM_CPLT_WQ_NAME … /* * SSAM_CPLT_WQ_BATCH - Maximum number of event item completions executed per * work execution. Used to prevent livelocking of the workqueue. Value chosen * via educated guess, may be adjusted. */ #define SSAM_CPLT_WQ_BATCH … /* * SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN - Maximum payload length for a cached * &struct ssam_event_item. * * This length has been chosen to be accommodate standard touchpad and * keyboard input events. Events with larger payloads will be allocated * separately. */ #define SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN … static struct kmem_cache *ssam_event_item_cache; /** * ssam_event_item_cache_init() - Initialize the event item cache. */ int ssam_event_item_cache_init(void) { … } /** * ssam_event_item_cache_destroy() - Deinitialize the event item cache. */ void ssam_event_item_cache_destroy(void) { … } static void __ssam_event_item_free_cached(struct ssam_event_item *item) { … } static void __ssam_event_item_free_generic(struct ssam_event_item *item) { … } /** * ssam_event_item_free() - Free the provided event item. * @item: The event item to free. */ static void ssam_event_item_free(struct ssam_event_item *item) { … } /** * ssam_event_item_alloc() - Allocate an event item with the given payload size. * @len: The event payload length. * @flags: The flags used for allocation. * * Allocate an event item with the given payload size, preferring allocation * from the event item cache if the payload is small enough (i.e. smaller than * %SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN). Sets the item operations and payload * length values. The item free callback (``ops.free``) should not be * overwritten after this call. * * Return: Returns the newly allocated event item. */ static struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags) { … } /** * ssam_event_queue_push() - Push an event item to the event queue. * @q: The event queue. * @item: The item to add. */ static void ssam_event_queue_push(struct ssam_event_queue *q, struct ssam_event_item *item) { … } /** * ssam_event_queue_pop() - Pop the next event item from the event queue. * @q: The event queue. * * Returns and removes the next event item from the queue. Returns %NULL If * there is no event item left. */ static struct ssam_event_item *ssam_event_queue_pop(struct ssam_event_queue *q) { … } /** * ssam_event_queue_is_empty() - Check if the event queue is empty. * @q: The event queue. */ static bool ssam_event_queue_is_empty(struct ssam_event_queue *q) { … } /** * ssam_cplt_get_event_queue() - Get the event queue for the given parameters. * @cplt: The completion system on which to look for the queue. * @tid: The target ID of the queue. * @rqid: The request ID representing the event ID for which to get the queue. * * Return: Returns the event queue corresponding to the event type described * by the given parameters. If the request ID does not represent an event, * this function returns %NULL. If the target ID is not supported, this * function will fall back to the default target ID (``tid = 1``). */ static struct ssam_event_queue *ssam_cplt_get_event_queue(struct ssam_cplt *cplt, u8 tid, u16 rqid) { … } /** * ssam_cplt_submit() - Submit a work item to the completion system workqueue. * @cplt: The completion system. * @work: The work item to submit. */ static bool ssam_cplt_submit(struct ssam_cplt *cplt, struct work_struct *work) { … } /** * ssam_cplt_submit_event() - Submit an event to the completion system. * @cplt: The completion system. * @item: The event item to submit. * * Submits the event to the completion system by queuing it on the event item * queue and queuing the respective event queue work item on the completion * workqueue, which will eventually complete the event. * * Return: Returns zero on success, %-EINVAL if there is no event queue that * can handle the given event item. */ static int ssam_cplt_submit_event(struct ssam_cplt *cplt, struct ssam_event_item *item) { … } /** * ssam_cplt_flush() - Flush the completion system. * @cplt: The completion system. * * Flush the completion system by waiting until all currently submitted work * items have been completed. * * Note: This function does not guarantee that all events will have been * handled once this call terminates. In case of a larger number of * to-be-completed events, the event queue work function may re-schedule its * work item, which this flush operation will ignore. * * This operation is only intended to, during normal operation prior to * shutdown, try to complete most events and requests to get them out of the * system while the system is still fully operational. It does not aim to * provide any guarantee that all of them have been handled. */ static void ssam_cplt_flush(struct ssam_cplt *cplt) { … } static void ssam_event_queue_work_fn(struct work_struct *work) { … } /** * ssam_event_queue_init() - Initialize an event queue. * @cplt: The completion system on which the queue resides. * @evq: The event queue to initialize. */ static void ssam_event_queue_init(struct ssam_cplt *cplt, struct ssam_event_queue *evq) { … } /** * ssam_cplt_init() - Initialize completion system. * @cplt: The completion system to initialize. * @dev: The device used for logging. */ static int ssam_cplt_init(struct ssam_cplt *cplt, struct device *dev) { … } /** * ssam_cplt_destroy() - Deinitialize the completion system. * @cplt: The completion system to deinitialize. * * Deinitialize the given completion system and ensure that all pending, i.e. * yet-to-be-completed, event items and requests have been handled. */ static void ssam_cplt_destroy(struct ssam_cplt *cplt) { … } /* -- Main SSAM device structures. ------------------------------------------ */ /** * ssam_controller_device() - Get the &struct device associated with this * controller. * @c: The controller for which to get the device. * * Return: Returns the &struct device associated with this controller, * providing its lower-level transport. */ struct device *ssam_controller_device(struct ssam_controller *c) { … } EXPORT_SYMBOL_GPL(…); static void __ssam_controller_release(struct kref *kref) { … } /** * ssam_controller_get() - Increment reference count of controller. * @c: The controller. * * Return: Returns the controller provided as input. */ struct ssam_controller *ssam_controller_get(struct ssam_controller *c) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_put() - Decrement reference count of controller. * @c: The controller. */ void ssam_controller_put(struct ssam_controller *c) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_statelock() - Lock the controller against state transitions. * @c: The controller to lock. * * Lock the controller against state transitions. Holding this lock guarantees * that the controller will not transition between states, i.e. if the * controller is in state "started", when this lock has been acquired, it will * remain in this state at least until the lock has been released. * * Multiple clients may concurrently hold this lock. In other words: The * ``statelock`` functions represent the read-lock part of a r/w-semaphore. * Actions causing state transitions of the controller must be executed while * holding the write-part of this r/w-semaphore (see ssam_controller_lock() * and ssam_controller_unlock() for that). * * See ssam_controller_stateunlock() for the corresponding unlock function. */ void ssam_controller_statelock(struct ssam_controller *c) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_stateunlock() - Unlock controller state transitions. * @c: The controller to unlock. * * See ssam_controller_statelock() for the corresponding lock function. */ void ssam_controller_stateunlock(struct ssam_controller *c) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_lock() - Acquire the main controller lock. * @c: The controller to lock. * * This lock must be held for any state transitions, including transition to * suspend/resumed states and during shutdown. See ssam_controller_statelock() * for more details on controller locking. * * See ssam_controller_unlock() for the corresponding unlock function. */ void ssam_controller_lock(struct ssam_controller *c) { … } /* * ssam_controller_unlock() - Release the main controller lock. * @c: The controller to unlock. * * See ssam_controller_lock() for the corresponding lock function. */ void ssam_controller_unlock(struct ssam_controller *c) { … } static void ssam_handle_event(struct ssh_rtl *rtl, const struct ssh_command *cmd, const struct ssam_span *data) { … } static const struct ssh_rtl_ops ssam_rtl_ops = …; static bool ssam_notifier_is_empty(struct ssam_controller *ctrl); static void ssam_notifier_unregister_all(struct ssam_controller *ctrl); #define SSAM_SSH_DSM_REVISION … /* d5e383e1-d892-4a76-89fc-f6aaae7ed5b5 */ static const guid_t SSAM_SSH_DSM_GUID = …; enum ssh_dsm_fn { … }; static int ssam_dsm_get_functions(acpi_handle handle, u64 *funcs) { … } static int ssam_dsm_load_u32(acpi_handle handle, u64 funcs, u64 func, u32 *ret) { … } /** * ssam_controller_caps_load_from_acpi() - Load controller capabilities from * ACPI _DSM. * @handle: The handle of the ACPI controller/SSH device. * @caps: Where to store the capabilities in. * * Initializes the given controller capabilities with default values, then * checks and, if the respective _DSM functions are available, loads the * actual capabilities from the _DSM. * * Return: Returns zero on success, a negative error code on failure. */ static int ssam_controller_caps_load_from_acpi(acpi_handle handle, struct ssam_controller_caps *caps) { … } /** * ssam_controller_init() - Initialize SSAM controller. * @ctrl: The controller to initialize. * @serdev: The serial device representing the underlying data transport. * * Initializes the given controller. Does neither start receiver nor * transmitter threads. After this call, the controller has to be hooked up to * the serdev core separately via &struct serdev_device_ops, relaying calls to * ssam_controller_receive_buf() and ssam_controller_write_wakeup(). Once the * controller has been hooked up, transmitter and receiver threads may be * started via ssam_controller_start(). These setup steps need to be completed * before controller can be used for requests. */ int ssam_controller_init(struct ssam_controller *ctrl, struct serdev_device *serdev) { … } /** * ssam_controller_start() - Start the receiver and transmitter threads of the * controller. * @ctrl: The controller. * * Note: When this function is called, the controller should be properly * hooked up to the serdev core via &struct serdev_device_ops. Please refer * to ssam_controller_init() for more details on controller initialization. * * This function must be called with the main controller lock held (i.e. by * calling ssam_controller_lock()). */ int ssam_controller_start(struct ssam_controller *ctrl) { … } /* * SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT - Timeout for flushing requests during * shutdown. * * Chosen to be larger than one full request timeout, including packets timing * out. This value should give ample time to complete any outstanding requests * during normal operation and account for the odd package timeout. */ #define SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT … /** * ssam_controller_shutdown() - Shut down the controller. * @ctrl: The controller. * * Shuts down the controller by flushing all pending requests and stopping the * transmitter and receiver threads. All requests submitted after this call * will fail with %-ESHUTDOWN. While it is discouraged to do so, this function * is safe to use in parallel with ongoing request submission. * * In the course of this shutdown procedure, all currently registered * notifiers will be unregistered. It is, however, strongly recommended to not * rely on this behavior, and instead the party registering the notifier * should unregister it before the controller gets shut down, e.g. via the * SSAM bus which guarantees client devices to be removed before a shutdown. * * Note that events may still be pending after this call, but, due to the * notifiers being unregistered, these events will be dropped when the * controller is subsequently destroyed via ssam_controller_destroy(). * * This function must be called with the main controller lock held (i.e. by * calling ssam_controller_lock()). */ void ssam_controller_shutdown(struct ssam_controller *ctrl) { … } /** * ssam_controller_destroy() - Destroy the controller and free its resources. * @ctrl: The controller. * * Ensures that all resources associated with the controller get freed. This * function should only be called after the controller has been stopped via * ssam_controller_shutdown(). In general, this function should not be called * directly. The only valid place to call this function directly is during * initialization, before the controller has been fully initialized and passed * to other processes. This function is called automatically when the * reference count of the controller reaches zero. * * This function must be called with the main controller lock held (i.e. by * calling ssam_controller_lock()). */ void ssam_controller_destroy(struct ssam_controller *ctrl) { … } /** * ssam_controller_suspend() - Suspend the controller. * @ctrl: The controller to suspend. * * Marks the controller as suspended. Note that display-off and D0-exit * notifications have to be sent manually before transitioning the controller * into the suspended state via this function. * * See ssam_controller_resume() for the corresponding resume function. * * Return: Returns %-EINVAL if the controller is currently not in the * "started" state. */ int ssam_controller_suspend(struct ssam_controller *ctrl) { … } /** * ssam_controller_resume() - Resume the controller from suspend. * @ctrl: The controller to resume. * * Resume the controller from the suspended state it was put into via * ssam_controller_suspend(). This function does not issue display-on and * D0-entry notifications. If required, those have to be sent manually after * this call. * * Return: Returns %-EINVAL if the controller is currently not suspended. */ int ssam_controller_resume(struct ssam_controller *ctrl) { … } /* -- Top-level request interface ------------------------------------------- */ /** * ssam_request_write_data() - Construct and write SAM request message to * buffer. * @buf: The buffer to write the data to. * @ctrl: The controller via which the request will be sent. * @spec: The request data and specification. * * Constructs a SAM/SSH request message and writes it to the provided buffer. * The request and transport counters, specifically RQID and SEQ, will be set * in this call. These counters are obtained from the controller. It is thus * only valid to send the resulting message via the controller specified here. * * For calculation of the required buffer size, refer to the * SSH_COMMAND_MESSAGE_LENGTH() macro. * * Return: Returns the number of bytes used in the buffer on success. Returns * %-EINVAL if the payload length provided in the request specification is too * large (larger than %SSH_COMMAND_MAX_PAYLOAD_SIZE) or if the provided buffer * is too small. */ ssize_t ssam_request_write_data(struct ssam_span *buf, struct ssam_controller *ctrl, const struct ssam_request *spec) { … } EXPORT_SYMBOL_GPL(…); static void ssam_request_sync_complete(struct ssh_request *rqst, const struct ssh_command *cmd, const struct ssam_span *data, int status) { … } static void ssam_request_sync_release(struct ssh_request *rqst) { … } static const struct ssh_request_ops ssam_request_sync_ops = …; /** * ssam_request_sync_alloc() - Allocate a synchronous request. * @payload_len: The length of the request payload. * @flags: Flags used for allocation. * @rqst: Where to store the pointer to the allocated request. * @buffer: Where to store the buffer descriptor for the message buffer of * the request. * * Allocates a synchronous request with corresponding message buffer. The * request still needs to be initialized ssam_request_sync_init() before * it can be submitted, and the message buffer data must still be set to the * returned buffer via ssam_request_sync_set_data() after it has been filled, * if need be with adjusted message length. * * After use, the request and its corresponding message buffer should be freed * via ssam_request_sync_free(). The buffer must not be freed separately. * * Return: Returns zero on success, %-ENOMEM if the request could not be * allocated. */ int ssam_request_sync_alloc(size_t payload_len, gfp_t flags, struct ssam_request_sync **rqst, struct ssam_span *buffer) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_request_sync_free() - Free a synchronous request. * @rqst: The request to be freed. * * Free a synchronous request and its corresponding buffer allocated with * ssam_request_sync_alloc(). Do not use for requests allocated on the stack * or via any other function. * * Warning: The caller must ensure that the request is not in use any more. * I.e. the caller must ensure that it has the only reference to the request * and the request is not currently pending. This means that the caller has * either never submitted the request, request submission has failed, or the * caller has waited until the submitted request has been completed via * ssam_request_sync_wait(). */ void ssam_request_sync_free(struct ssam_request_sync *rqst) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_request_sync_init() - Initialize a synchronous request struct. * @rqst: The request to initialize. * @flags: The request flags. * * Initializes the given request struct. Does not initialize the request * message data. This has to be done explicitly after this call via * ssam_request_sync_set_data() and the actual message data has to be written * via ssam_request_write_data(). * * Return: Returns zero on success or %-EINVAL if the given flags are invalid. */ int ssam_request_sync_init(struct ssam_request_sync *rqst, enum ssam_request_flags flags) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_request_sync_submit() - Submit a synchronous request. * @ctrl: The controller with which to submit the request. * @rqst: The request to submit. * * Submit a synchronous request. The request has to be initialized and * properly set up, including response buffer (may be %NULL if no response is * expected) and command message data. This function does not wait for the * request to be completed. * * If this function succeeds, ssam_request_sync_wait() must be used to ensure * that the request has been completed before the response data can be * accessed and/or the request can be freed. On failure, the request may * immediately be freed. * * This function may only be used if the controller is active, i.e. has been * initialized and not suspended. */ int ssam_request_sync_submit(struct ssam_controller *ctrl, struct ssam_request_sync *rqst) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_request_do_sync() - Execute a synchronous request. * @ctrl: The controller via which the request will be submitted. * @spec: The request specification and payload. * @rsp: The response buffer. * * Allocates a synchronous request with its message data buffer on the heap * via ssam_request_sync_alloc(), fully initializes it via the provided * request specification, submits it, and finally waits for its completion * before freeing it and returning its status. * * Return: Returns the status of the request or any failure during setup. */ int ssam_request_do_sync(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_request_do_sync_with_buffer() - Execute a synchronous request with the * provided buffer as back-end for the message buffer. * @ctrl: The controller via which the request will be submitted. * @spec: The request specification and payload. * @rsp: The response buffer. * @buf: The buffer for the request message data. * * Allocates a synchronous request struct on the stack, fully initializes it * using the provided buffer as message data buffer, submits it, and then * waits for its completion before returning its status. The * SSH_COMMAND_MESSAGE_LENGTH() macro can be used to compute the required * message buffer size. * * This function does essentially the same as ssam_request_do_sync(), but * instead of dynamically allocating the request and message data buffer, it * uses the provided message data buffer and stores the (small) request struct * on the heap. * * Return: Returns the status of the request or any failure during setup. */ int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp, struct ssam_span *buf) { … } EXPORT_SYMBOL_GPL(…); /* -- Internal SAM requests. ------------------------------------------------ */ SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_get_firmware_version, __le32, { .target_category = SSAM_SSH_TC_SAM, .target_id = SSAM_SSH_TID_SAM, .command_id = 0x13, .instance_id = 0x00, }); SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_off, u8, { .target_category = SSAM_SSH_TC_SAM, .target_id = SSAM_SSH_TID_SAM, .command_id = 0x15, .instance_id = 0x00, }); SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_on, u8, { .target_category = SSAM_SSH_TC_SAM, .target_id = SSAM_SSH_TID_SAM, .command_id = 0x16, .instance_id = 0x00, }); SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_exit, u8, { .target_category = SSAM_SSH_TC_SAM, .target_id = SSAM_SSH_TID_SAM, .command_id = 0x33, .instance_id = 0x00, }); SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_entry, u8, { .target_category = SSAM_SSH_TC_SAM, .target_id = SSAM_SSH_TID_SAM, .command_id = 0x34, .instance_id = 0x00, }); /** * struct ssh_notification_params - Command payload to enable/disable SSH * notifications. * @target_category: The target category for which notifications should be * enabled/disabled. * @flags: Flags determining how notifications are being sent. * @request_id: The request ID that is used to send these notifications. * @instance_id: The specific instance in the given target category for * which notifications should be enabled. */ struct ssh_notification_params { … } __packed; static_assert(…); static int __ssam_ssh_event_request(struct ssam_controller *ctrl, struct ssam_event_registry reg, u8 cid, struct ssam_event_id id, u8 flags) { … } /** * ssam_ssh_event_enable() - Enable SSH event. * @ctrl: The controller for which to enable the event. * @reg: The event registry describing what request to use for enabling and * disabling the event. * @id: The event identifier. * @flags: The event flags. * * Enables the specified event on the EC. This function does not manage * reference counting of enabled events and is basically only a wrapper for * the raw EC request. If the specified event is already enabled, the EC will * ignore this request. * * Return: Returns the status of the executed SAM request (zero on success and * negative on direct failure) or %-EPROTO if the request response indicates a * failure. */ static int ssam_ssh_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags) { … } /** * ssam_ssh_event_disable() - Disable SSH event. * @ctrl: The controller for which to disable the event. * @reg: The event registry describing what request to use for enabling and * disabling the event (must be same as used when enabling the event). * @id: The event identifier. * @flags: The event flags (likely ignored for disabling of events). * * Disables the specified event on the EC. This function does not manage * reference counting of enabled events and is basically only a wrapper for * the raw EC request. If the specified event is already disabled, the EC will * ignore this request. * * Return: Returns the status of the executed SAM request (zero on success and * negative on direct failure) or %-EPROTO if the request response indicates a * failure. */ static int ssam_ssh_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags) { … } /* -- Wrappers for internal SAM requests. ----------------------------------- */ /** * ssam_get_firmware_version() - Get the SAM/EC firmware version. * @ctrl: The controller. * @version: Where to store the version number. * * Return: Returns zero on success or the status of the executed SAM request * if that request failed. */ int ssam_get_firmware_version(struct ssam_controller *ctrl, u32 *version) { … } /** * ssam_ctrl_notif_display_off() - Notify EC that the display has been turned * off. * @ctrl: The controller. * * Notify the EC that the display has been turned off and the driver may enter * a lower-power state. This will prevent events from being sent directly. * Rather, the EC signals an event by pulling the wakeup GPIO high for as long * as there are pending events. The events then need to be manually released, * one by one, via the GPIO callback request. All pending events accumulated * during this state can also be released by issuing the display-on * notification, e.g. via ssam_ctrl_notif_display_on(), which will also reset * the GPIO. * * On some devices, specifically ones with an integrated keyboard, the keyboard * backlight will be turned off by this call. * * This function will only send the display-off notification command if * display notifications are supported by the EC. Currently all known devices * support these notifications. * * Use ssam_ctrl_notif_display_on() to reverse the effects of this function. * * Return: Returns zero on success or if no request has been executed, the * status of the executed SAM request if that request failed, or %-EPROTO if * an unexpected response has been received. */ int ssam_ctrl_notif_display_off(struct ssam_controller *ctrl) { … } /** * ssam_ctrl_notif_display_on() - Notify EC that the display has been turned on. * @ctrl: The controller. * * Notify the EC that the display has been turned back on and the driver has * exited its lower-power state. This notification is the counterpart to the * display-off notification sent via ssam_ctrl_notif_display_off() and will * reverse its effects, including resetting events to their default behavior. * * This function will only send the display-on notification command if display * notifications are supported by the EC. Currently all known devices support * these notifications. * * See ssam_ctrl_notif_display_off() for more details. * * Return: Returns zero on success or if no request has been executed, the * status of the executed SAM request if that request failed, or %-EPROTO if * an unexpected response has been received. */ int ssam_ctrl_notif_display_on(struct ssam_controller *ctrl) { … } /** * ssam_ctrl_notif_d0_exit() - Notify EC that the driver/device exits the D0 * power state. * @ctrl: The controller * * Notifies the EC that the driver prepares to exit the D0 power state in * favor of a lower-power state. Exact effects of this function related to the * EC are currently unknown. * * This function will only send the D0-exit notification command if D0-state * notifications are supported by the EC. Only newer Surface generations * support these notifications. * * Use ssam_ctrl_notif_d0_entry() to reverse the effects of this function. * * Return: Returns zero on success or if no request has been executed, the * status of the executed SAM request if that request failed, or %-EPROTO if * an unexpected response has been received. */ int ssam_ctrl_notif_d0_exit(struct ssam_controller *ctrl) { … } /** * ssam_ctrl_notif_d0_entry() - Notify EC that the driver/device enters the D0 * power state. * @ctrl: The controller * * Notifies the EC that the driver has exited a lower-power state and entered * the D0 power state. Exact effects of this function related to the EC are * currently unknown. * * This function will only send the D0-entry notification command if D0-state * notifications are supported by the EC. Only newer Surface generations * support these notifications. * * See ssam_ctrl_notif_d0_exit() for more details. * * Return: Returns zero on success or if no request has been executed, the * status of the executed SAM request if that request failed, or %-EPROTO if * an unexpected response has been received. */ int ssam_ctrl_notif_d0_entry(struct ssam_controller *ctrl) { … } /* -- Top-level event registry interface. ----------------------------------- */ /** * ssam_nf_refcount_enable() - Enable event for reference count entry if it has * not already been enabled. * @ctrl: The controller to enable the event on. * @entry: The reference count entry for the event to be enabled. * @flags: The flags used for enabling the event on the EC. * * Enable the event associated with the given reference count entry if the * reference count equals one, i.e. the event has not previously been enabled. * If the event has already been enabled (i.e. reference count not equal to * one), check that the flags used for enabling match and warn about this if * they do not. * * This does not modify the reference count itself, which is done with * ssam_nf_refcount_inc() / ssam_nf_refcount_dec(). * * Note: ``nf->lock`` must be held when calling this function. * * Return: Returns zero on success. If the event is enabled by this call, * returns the status of the event-enable EC command. */ static int ssam_nf_refcount_enable(struct ssam_controller *ctrl, struct ssam_nf_refcount_entry *entry, u8 flags) { … } /** * ssam_nf_refcount_disable_free() - Disable event for reference count entry if * it is no longer in use and free the corresponding entry. * @ctrl: The controller to disable the event on. * @entry: The reference count entry for the event to be disabled. * @flags: The flags used for enabling the event on the EC. * @ec: Flag specifying if the event should actually be disabled on the EC. * * If ``ec`` equals ``true`` and the reference count equals zero (i.e. the * event is no longer requested by any client), the specified event will be * disabled on the EC via the corresponding request. * * If ``ec`` equals ``false``, no request will be sent to the EC and the event * can be considered in a detached state (i.e. no longer used but still * enabled). Disabling an event via this method may be required for * hot-removable devices, where event disable requests may time out after the * device has been physically removed. * * In both cases, if the reference count equals zero, the corresponding * reference count entry will be freed. The reference count entry must not be * used any more after a call to this function. * * Also checks if the flags used for disabling the event match the flags used * for enabling the event and warns if they do not (regardless of reference * count). * * This does not modify the reference count itself, which is done with * ssam_nf_refcount_inc() / ssam_nf_refcount_dec(). * * Note: ``nf->lock`` must be held when calling this function. * * Return: Returns zero on success. If the event is disabled by this call, * returns the status of the event-enable EC command. */ static int ssam_nf_refcount_disable_free(struct ssam_controller *ctrl, struct ssam_nf_refcount_entry *entry, u8 flags, bool ec) { … } /** * ssam_notifier_register() - Register an event notifier. * @ctrl: The controller to register the notifier on. * @n: The event notifier to register. * * Register an event notifier. Increment the usage counter of the associated * SAM event if the notifier is not marked as an observer. If the event is not * marked as an observer and is currently not enabled, it will be enabled * during this call. If the notifier is marked as an observer, no attempt will * be made at enabling any event and no reference count will be modified. * * Notifiers marked as observers do not need to be associated with one specific * event, i.e. as long as no event matching is performed, only the event target * category needs to be set. * * Return: Returns zero on success, %-ENOSPC if there have already been * %INT_MAX notifiers for the event ID/type associated with the notifier block * registered, %-ENOMEM if the corresponding event entry could not be * allocated. If this is the first time that a notifier block is registered * for the specific associated event, returns the status of the event-enable * EC-command. */ int ssam_notifier_register(struct ssam_controller *ctrl, struct ssam_event_notifier *n) { … } EXPORT_SYMBOL_GPL(…); /** * __ssam_notifier_unregister() - Unregister an event notifier. * @ctrl: The controller the notifier has been registered on. * @n: The event notifier to unregister. * @disable: Whether to disable the corresponding event on the EC. * * Unregister an event notifier. Decrement the usage counter of the associated * SAM event if the notifier is not marked as an observer. If the usage counter * reaches zero and ``disable`` equals ``true``, the event will be disabled. * * Useful for hot-removable devices, where communication may fail once the * device has been physically removed. In that case, specifying ``disable`` as * ``false`` avoids communication with the EC. * * Return: Returns zero on success, %-ENOENT if the given notifier block has * not been registered on the controller. If the given notifier block was the * last one associated with its specific event, returns the status of the * event-disable EC-command. */ int __ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n, bool disable) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_event_enable() - Enable the specified event. * @ctrl: The controller to enable the event for. * @reg: The event registry to use for enabling the event. * @id: The event ID specifying the event to be enabled. * @flags: The SAM event flags used for enabling the event. * * Increment the event reference count of the specified event. If the event has * not been enabled previously, it will be enabled by this call. * * Note: In general, ssam_notifier_register() with a non-observer notifier * should be preferred for enabling/disabling events, as this will guarantee * proper ordering and event forwarding in case of errors during event * enabling/disabling. * * Return: Returns zero on success, %-ENOSPC if the reference count for the * specified event has reached its maximum, %-ENOMEM if the corresponding event * entry could not be allocated. If this is the first time that this event has * been enabled (i.e. the reference count was incremented from zero to one by * this call), returns the status of the event-enable EC-command. */ int ssam_controller_event_enable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_controller_event_disable() - Disable the specified event. * @ctrl: The controller to disable the event for. * @reg: The event registry to use for disabling the event. * @id: The event ID specifying the event to be disabled. * @flags: The flags used when enabling the event. * * Decrement the reference count of the specified event. If the reference count * reaches zero, the event will be disabled. * * Note: In general, ssam_notifier_register()/ssam_notifier_unregister() with a * non-observer notifier should be preferred for enabling/disabling events, as * this will guarantee proper ordering and event forwarding in case of errors * during event enabling/disabling. * * Return: Returns zero on success, %-ENOENT if the given event has not been * enabled on the controller. If the reference count of the event reaches zero * during this call, returns the status of the event-disable EC-command. */ int ssam_controller_event_disable(struct ssam_controller *ctrl, struct ssam_event_registry reg, struct ssam_event_id id, u8 flags) { … } EXPORT_SYMBOL_GPL(…); /** * ssam_notifier_disable_registered() - Disable events for all registered * notifiers. * @ctrl: The controller for which to disable the notifiers/events. * * Disables events for all currently registered notifiers. In case of an error * (EC command failing), all previously disabled events will be restored and * the error code returned. * * This function is intended to disable all events prior to hibernation entry. * See ssam_notifier_restore_registered() to restore/re-enable all events * disabled with this function. * * Note that this function will not disable events for notifiers registered * after calling this function. It should thus be made sure that no new * notifiers are going to be added after this call and before the corresponding * call to ssam_notifier_restore_registered(). * * Return: Returns zero on success. In case of failure returns the error code * returned by the failed EC command to disable an event. */ int ssam_notifier_disable_registered(struct ssam_controller *ctrl) { … } /** * ssam_notifier_restore_registered() - Restore/re-enable events for all * registered notifiers. * @ctrl: The controller for which to restore the notifiers/events. * * Restores/re-enables all events for which notifiers have been registered on * the given controller. In case of a failure, the error is logged and the * function continues to try and enable the remaining events. * * This function is intended to restore/re-enable all registered events after * hibernation. See ssam_notifier_disable_registered() for the counter part * disabling the events and more details. */ void ssam_notifier_restore_registered(struct ssam_controller *ctrl) { … } /** * ssam_notifier_is_empty() - Check if there are any registered notifiers. * @ctrl: The controller to check on. * * Return: Returns %true if there are currently no notifiers registered on the * controller, %false otherwise. */ static bool ssam_notifier_is_empty(struct ssam_controller *ctrl) { … } /** * ssam_notifier_unregister_all() - Unregister all currently registered * notifiers. * @ctrl: The controller to unregister the notifiers on. * * Unregisters all currently registered notifiers. This function is used to * ensure that all notifiers will be unregistered and associated * entries/resources freed when the controller is being shut down. */ static void ssam_notifier_unregister_all(struct ssam_controller *ctrl) { … } /* -- Wakeup IRQ. ----------------------------------------------------------- */ static irqreturn_t ssam_irq_handle(int irq, void *dev_id) { … } /** * ssam_irq_setup() - Set up SAM EC wakeup-GPIO interrupt. * @ctrl: The controller for which the IRQ should be set up. * * Set up an IRQ for the wakeup-GPIO pin of the SAM EC. This IRQ can be used * to wake the device from a low power state. * * Note that this IRQ can only be triggered while the EC is in the display-off * state. In this state, events are not sent to the host in the usual way. * Instead the wakeup-GPIO gets pulled to "high" as long as there are pending * events and these events need to be released one-by-one via the GPIO * callback request, either until there are no events left and the GPIO is * reset, or all at once by transitioning the EC out of the display-off state, * which will also clear the GPIO. * * Not all events, however, should trigger a full system wakeup. Instead the * driver should, if necessary, inspect and forward each event to the * corresponding subsystem, which in turn should decide if the system needs to * be woken up. This logic has not been implemented yet, thus wakeup by this * IRQ should be disabled by default to avoid spurious wake-ups, caused, for * example, by the remaining battery percentage changing. Refer to comments in * this function and comments in the corresponding IRQ handler for more * details on how this should be implemented. * * See also ssam_ctrl_notif_display_off() and ssam_ctrl_notif_display_off() * for functions to transition the EC into and out of the display-off state as * well as more details on it. * * The IRQ is disabled by default and has to be enabled before it can wake up * the device from suspend via ssam_irq_arm_for_wakeup(). On teardown, the IRQ * should be freed via ssam_irq_free(). */ int ssam_irq_setup(struct ssam_controller *ctrl) { … } /** * ssam_irq_free() - Free SAM EC wakeup-GPIO interrupt. * @ctrl: The controller for which the IRQ should be freed. * * Free the wakeup-GPIO IRQ previously set-up via ssam_irq_setup(). */ void ssam_irq_free(struct ssam_controller *ctrl) { … } /** * ssam_irq_arm_for_wakeup() - Arm the EC IRQ for wakeup, if enabled. * @ctrl: The controller for which the IRQ should be armed. * * Sets up the IRQ so that it can be used to wake the device. Specifically, * this function enables the irq and then, if the device is allowed to wake up * the system, calls enable_irq_wake(). See ssam_irq_disarm_wakeup() for the * corresponding function to disable the IRQ. * * This function is intended to arm the IRQ before entering S2idle suspend. * * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must * be balanced. */ int ssam_irq_arm_for_wakeup(struct ssam_controller *ctrl) { … } /** * ssam_irq_disarm_wakeup() - Disarm the wakeup IRQ. * @ctrl: The controller for which the IRQ should be disarmed. * * Disarm the IRQ previously set up for wake via ssam_irq_arm_for_wakeup(). * * This function is intended to disarm the IRQ after exiting S2idle suspend. * * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must * be balanced. */ void ssam_irq_disarm_wakeup(struct ssam_controller *ctrl) { … }
Codebase Browser
linux