1 // SPDX-License-Identifier: GPL-2.0+
3 * Main SSAM/SSH controller structure and functionality.
5 * Copyright (C) 2019-2020 Maximilian Luz <luzmaximilian@gmail.com>
8 #include <linux/acpi.h>
9 #include <linux/atomic.h>
10 #include <linux/completion.h>
11 #include <linux/gpio/consumer.h>
12 #include <linux/interrupt.h>
13 #include <linux/kref.h>
14 #include <linux/limits.h>
15 #include <linux/list.h>
16 #include <linux/lockdep.h>
17 #include <linux/mutex.h>
18 #include <linux/rculist.h>
19 #include <linux/rbtree.h>
20 #include <linux/rwsem.h>
21 #include <linux/serdev.h>
22 #include <linux/slab.h>
23 #include <linux/spinlock.h>
24 #include <linux/srcu.h>
25 #include <linux/types.h>
26 #include <linux/workqueue.h>
28 #include <linux/surface_aggregator/controller.h>
29 #include <linux/surface_aggregator/serial_hub.h>
31 #include "controller.h"
33 #include "ssh_request_layer.h"
38 /* -- Safe counters. -------------------------------------------------------- */
41 * ssh_seq_reset() - Reset/initialize sequence ID counter.
42 * @c: The counter to reset.
44 static void ssh_seq_reset(struct ssh_seq_counter *c)
46 WRITE_ONCE(c->value, 0);
50 * ssh_seq_next() - Get next sequence ID.
51 * @c: The counter providing the sequence IDs.
53 * Return: Returns the next sequence ID of the counter.
55 static u8 ssh_seq_next(struct ssh_seq_counter *c)
57 u8 old = READ_ONCE(c->value);
61 while (unlikely((ret = cmpxchg(&c->value, old, new)) != old)) {
70 * ssh_rqid_reset() - Reset/initialize request ID counter.
71 * @c: The counter to reset.
73 static void ssh_rqid_reset(struct ssh_rqid_counter *c)
75 WRITE_ONCE(c->value, 0);
79 * ssh_rqid_next() - Get next request ID.
80 * @c: The counter providing the request IDs.
82 * Return: Returns the next request ID of the counter, skipping any reserved
85 static u16 ssh_rqid_next(struct ssh_rqid_counter *c)
87 u16 old = READ_ONCE(c->value);
88 u16 new = ssh_rqid_next_valid(old);
91 while (unlikely((ret = cmpxchg(&c->value, old, new)) != old)) {
93 new = ssh_rqid_next_valid(old);
100 /* -- Event notifier/callbacks. --------------------------------------------- */
102 * The notifier system is based on linux/notifier.h, specifically the SRCU
103 * implementation. The difference to that is, that some bits of the notifier
104 * call return value can be tracked across multiple calls. This is done so
105 * that handling of events can be tracked and a warning can be issued in case
106 * an event goes unhandled. The idea of that warning is that it should help
107 * discover and identify new/currently unimplemented features.
111 * ssam_event_matches_notifier() - Test if an event matches a notifier.
112 * @n: The event notifier to test against.
113 * @event: The event to test.
115 * Return: Returns %true if the given event matches the given notifier
116 * according to the rules set in the notifier's event mask, %false otherwise.
118 static bool ssam_event_matches_notifier(const struct ssam_event_notifier *n,
119 const struct ssam_event *event)
121 bool match = n->event.id.target_category == event->target_category;
123 if (n->event.mask & SSAM_EVENT_MASK_TARGET)
124 match &= n->event.reg.target_id == event->target_id;
126 if (n->event.mask & SSAM_EVENT_MASK_INSTANCE)
127 match &= n->event.id.instance == event->instance_id;
133 * ssam_nfblk_call_chain() - Call event notifier callbacks of the given chain.
134 * @nh: The notifier head for which the notifier callbacks should be called.
135 * @event: The event data provided to the callbacks.
137 * Call all registered notifier callbacks in order of their priority until
138 * either no notifier is left or a notifier returns a value with the
139 * %SSAM_NOTIF_STOP bit set. Note that this bit is automatically set via
140 * ssam_notifier_from_errno() on any non-zero error value.
142 * Return: Returns the notifier status value, which contains the notifier
143 * status bits (%SSAM_NOTIF_HANDLED and %SSAM_NOTIF_STOP) as well as a
144 * potential error value returned from the last executed notifier callback.
145 * Use ssam_notifier_to_errno() to convert this value to the original error
148 static int ssam_nfblk_call_chain(struct ssam_nf_head *nh, struct ssam_event *event)
150 struct ssam_event_notifier *nf;
153 idx = srcu_read_lock(&nh->srcu);
155 list_for_each_entry_rcu(nf, &nh->head, base.node,
156 srcu_read_lock_held(&nh->srcu)) {
157 if (ssam_event_matches_notifier(nf, event)) {
158 ret = (ret & SSAM_NOTIF_STATE_MASK) | nf->base.fn(nf, event);
159 if (ret & SSAM_NOTIF_STOP)
164 srcu_read_unlock(&nh->srcu, idx);
169 * ssam_nfblk_insert() - Insert a new notifier block into the given notifier
171 * @nh: The notifier head into which the block should be inserted.
172 * @nb: The notifier block to add.
174 * Note: This function must be synchronized by the caller with respect to other
175 * insert, find, and/or remove calls by holding ``struct ssam_nf.lock``.
177 * Return: Returns zero on success, %-EEXIST if the notifier block has already
180 static int ssam_nfblk_insert(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)
182 struct ssam_notifier_block *p;
185 /* Runs under lock, no need for RCU variant. */
186 list_for_each(h, &nh->head) {
187 p = list_entry(h, struct ssam_notifier_block, node);
189 if (unlikely(p == nb)) {
190 WARN(1, "double register detected");
194 if (nb->priority > p->priority)
198 list_add_tail_rcu(&nb->node, h);
203 * ssam_nfblk_find() - Check if a notifier block is registered on the given
206 * @nh: The notifier head on which to search.
207 * @nb: The notifier block to search for.
209 * Note: This function must be synchronized by the caller with respect to other
210 * insert, find, and/or remove calls by holding ``struct ssam_nf.lock``.
212 * Return: Returns true if the given notifier block is registered on the given
213 * notifier head, false otherwise.
215 static bool ssam_nfblk_find(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)
217 struct ssam_notifier_block *p;
219 /* Runs under lock, no need for RCU variant. */
220 list_for_each_entry(p, &nh->head, node) {
229 * ssam_nfblk_remove() - Remove a notifier block from its notifier list.
230 * @nb: The notifier block to be removed.
232 * Note: This function must be synchronized by the caller with respect to
233 * other insert, find, and/or remove calls by holding ``struct ssam_nf.lock``.
234 * Furthermore, the caller _must_ ensure SRCU synchronization by calling
235 * synchronize_srcu() with ``nh->srcu`` after leaving the critical section, to
236 * ensure that the removed notifier block is not in use any more.
238 static void ssam_nfblk_remove(struct ssam_notifier_block *nb)
240 list_del_rcu(&nb->node);
244 * ssam_nf_head_init() - Initialize the given notifier head.
245 * @nh: The notifier head to initialize.
247 static int ssam_nf_head_init(struct ssam_nf_head *nh)
251 status = init_srcu_struct(&nh->srcu);
255 INIT_LIST_HEAD(&nh->head);
260 * ssam_nf_head_destroy() - Deinitialize the given notifier head.
261 * @nh: The notifier head to deinitialize.
263 static void ssam_nf_head_destroy(struct ssam_nf_head *nh)
265 cleanup_srcu_struct(&nh->srcu);
269 /* -- Event/notification registry. ------------------------------------------ */
272 * struct ssam_nf_refcount_key - Key used for event activation reference
274 * @reg: The registry via which the event is enabled/disabled.
275 * @id: The ID uniquely describing the event.
277 struct ssam_nf_refcount_key {
278 struct ssam_event_registry reg;
279 struct ssam_event_id id;
283 * struct ssam_nf_refcount_entry - RB-tree entry for reference counting event
285 * @node: The node of this entry in the rb-tree.
286 * @key: The key of the event.
287 * @refcount: The reference-count of the event.
288 * @flags: The flags used when enabling the event.
290 struct ssam_nf_refcount_entry {
292 struct ssam_nf_refcount_key key;
298 * ssam_nf_refcount_inc() - Increment reference-/activation-count of the given
300 * @nf: The notifier system reference.
301 * @reg: The registry used to enable/disable the event.
304 * Increments the reference-/activation-count associated with the specified
305 * event type/ID, allocating a new entry for this event ID if necessary. A
306 * newly allocated entry will have a refcount of one.
308 * Note: ``nf->lock`` must be held when calling this function.
310 * Return: Returns the refcount entry on success. Returns an error pointer
311 * with %-ENOSPC if there have already been %INT_MAX events of the specified
312 * ID and type registered, or %-ENOMEM if the entry could not be allocated.
314 static struct ssam_nf_refcount_entry *
315 ssam_nf_refcount_inc(struct ssam_nf *nf, struct ssam_event_registry reg,
316 struct ssam_event_id id)
318 struct ssam_nf_refcount_entry *entry;
319 struct ssam_nf_refcount_key key;
320 struct rb_node **link = &nf->refcount.rb_node;
321 struct rb_node *parent = NULL;
324 lockdep_assert_held(&nf->lock);
330 entry = rb_entry(*link, struct ssam_nf_refcount_entry, node);
333 cmp = memcmp(&key, &entry->key, sizeof(key));
335 link = &(*link)->rb_left;
336 } else if (cmp > 0) {
337 link = &(*link)->rb_right;
338 } else if (entry->refcount < INT_MAX) {
343 return ERR_PTR(-ENOSPC);
347 entry = kzalloc(sizeof(*entry), GFP_KERNEL);
349 return ERR_PTR(-ENOMEM);
354 rb_link_node(&entry->node, parent, link);
355 rb_insert_color(&entry->node, &nf->refcount);
361 * ssam_nf_refcount_dec() - Decrement reference-/activation-count of the given
363 * @nf: The notifier system reference.
364 * @reg: The registry used to enable/disable the event.
367 * Decrements the reference-/activation-count of the specified event,
368 * returning its entry. If the returned entry has a refcount of zero, the
369 * caller is responsible for freeing it using kfree().
371 * Note: ``nf->lock`` must be held when calling this function.
373 * Return: Returns the refcount entry on success or %NULL if the entry has not
376 static struct ssam_nf_refcount_entry *
377 ssam_nf_refcount_dec(struct ssam_nf *nf, struct ssam_event_registry reg,
378 struct ssam_event_id id)
380 struct ssam_nf_refcount_entry *entry;
381 struct ssam_nf_refcount_key key;
382 struct rb_node *node = nf->refcount.rb_node;
385 lockdep_assert_held(&nf->lock);
391 entry = rb_entry(node, struct ssam_nf_refcount_entry, node);
393 cmp = memcmp(&key, &entry->key, sizeof(key));
395 node = node->rb_left;
396 } else if (cmp > 0) {
397 node = node->rb_right;
400 if (entry->refcount == 0)
401 rb_erase(&entry->node, &nf->refcount);
411 * ssam_nf_refcount_empty() - Test if the notification system has any
412 * enabled/active events.
413 * @nf: The notification system.
415 static bool ssam_nf_refcount_empty(struct ssam_nf *nf)
417 return RB_EMPTY_ROOT(&nf->refcount);
421 * ssam_nf_call() - Call notification callbacks for the provided event.
422 * @nf: The notifier system
423 * @dev: The associated device, only used for logging.
424 * @rqid: The request ID of the event.
425 * @event: The event provided to the callbacks.
427 * Execute registered callbacks in order of their priority until either no
428 * callback is left or a callback returns a value with the %SSAM_NOTIF_STOP
429 * bit set. Note that this bit is set automatically when converting non-zero
430 * error values via ssam_notifier_from_errno() to notifier values.
432 * Also note that any callback that could handle an event should return a value
433 * with bit %SSAM_NOTIF_HANDLED set, indicating that the event does not go
434 * unhandled/ignored. In case no registered callback could handle an event,
435 * this function will emit a warning.
437 * In case a callback failed, this function will emit an error message.
439 static void ssam_nf_call(struct ssam_nf *nf, struct device *dev, u16 rqid,
440 struct ssam_event *event)
442 struct ssam_nf_head *nf_head;
445 if (!ssh_rqid_is_event(rqid)) {
446 dev_warn(dev, "event: unsupported rqid: %#06x\n", rqid);
450 nf_head = &nf->head[ssh_rqid_to_event(rqid)];
451 nf_ret = ssam_nfblk_call_chain(nf_head, event);
452 status = ssam_notifier_to_errno(nf_ret);
456 "event: error handling event: %d (tc: %#04x, tid: %#04x, cid: %#04x, iid: %#04x)\n",
457 status, event->target_category, event->target_id,
458 event->command_id, event->instance_id);
459 } else if (!(nf_ret & SSAM_NOTIF_HANDLED)) {
461 "event: unhandled event (rqid: %#04x, tc: %#04x, tid: %#04x, cid: %#04x, iid: %#04x)\n",
462 rqid, event->target_category, event->target_id,
463 event->command_id, event->instance_id);
468 * ssam_nf_init() - Initialize the notifier system.
469 * @nf: The notifier system to initialize.
471 static int ssam_nf_init(struct ssam_nf *nf)
475 for (i = 0; i < SSH_NUM_EVENTS; i++) {
476 status = ssam_nf_head_init(&nf->head[i]);
483 ssam_nf_head_destroy(&nf->head[i]);
488 mutex_init(&nf->lock);
493 * ssam_nf_destroy() - Deinitialize the notifier system.
494 * @nf: The notifier system to deinitialize.
496 static void ssam_nf_destroy(struct ssam_nf *nf)
500 for (i = 0; i < SSH_NUM_EVENTS; i++)
501 ssam_nf_head_destroy(&nf->head[i]);
503 mutex_destroy(&nf->lock);
507 /* -- Event/async request completion system. -------------------------------- */
509 #define SSAM_CPLT_WQ_NAME "ssam_cpltq"
512 * SSAM_CPLT_WQ_BATCH - Maximum number of event item completions executed per
513 * work execution. Used to prevent livelocking of the workqueue. Value chosen
514 * via educated guess, may be adjusted.
516 #define SSAM_CPLT_WQ_BATCH 10
519 * SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN - Maximum payload length for a cached
520 * &struct ssam_event_item.
522 * This length has been chosen to be accommodate standard touchpad and
523 * keyboard input events. Events with larger payloads will be allocated
526 #define SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN 32
528 static struct kmem_cache *ssam_event_item_cache;
531 * ssam_event_item_cache_init() - Initialize the event item cache.
533 int ssam_event_item_cache_init(void)
535 const unsigned int size = sizeof(struct ssam_event_item)
536 + SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN;
537 const unsigned int align = __alignof__(struct ssam_event_item);
538 struct kmem_cache *cache;
540 cache = kmem_cache_create("ssam_event_item", size, align, 0, NULL);
544 ssam_event_item_cache = cache;
549 * ssam_event_item_cache_destroy() - Deinitialize the event item cache.
551 void ssam_event_item_cache_destroy(void)
553 kmem_cache_destroy(ssam_event_item_cache);
554 ssam_event_item_cache = NULL;
557 static void __ssam_event_item_free_cached(struct ssam_event_item *item)
559 kmem_cache_free(ssam_event_item_cache, item);
562 static void __ssam_event_item_free_generic(struct ssam_event_item *item)
568 * ssam_event_item_free() - Free the provided event item.
569 * @item: The event item to free.
571 static void ssam_event_item_free(struct ssam_event_item *item)
573 trace_ssam_event_item_free(item);
574 item->ops.free(item);
578 * ssam_event_item_alloc() - Allocate an event item with the given payload size.
579 * @len: The event payload length.
580 * @flags: The flags used for allocation.
582 * Allocate an event item with the given payload size, preferring allocation
583 * from the event item cache if the payload is small enough (i.e. smaller than
584 * %SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN). Sets the item operations and payload
585 * length values. The item free callback (``ops.free``) should not be
586 * overwritten after this call.
588 * Return: Returns the newly allocated event item.
590 static struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags)
592 struct ssam_event_item *item;
594 if (len <= SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN) {
595 item = kmem_cache_alloc(ssam_event_item_cache, flags);
599 item->ops.free = __ssam_event_item_free_cached;
601 item = kzalloc(struct_size(item, event.data, len), flags);
605 item->ops.free = __ssam_event_item_free_generic;
608 item->event.length = len;
610 trace_ssam_event_item_alloc(item, len);
615 * ssam_event_queue_push() - Push an event item to the event queue.
616 * @q: The event queue.
617 * @item: The item to add.
619 static void ssam_event_queue_push(struct ssam_event_queue *q,
620 struct ssam_event_item *item)
623 list_add_tail(&item->node, &q->head);
624 spin_unlock(&q->lock);
628 * ssam_event_queue_pop() - Pop the next event item from the event queue.
629 * @q: The event queue.
631 * Returns and removes the next event item from the queue. Returns %NULL If
632 * there is no event item left.
634 static struct ssam_event_item *ssam_event_queue_pop(struct ssam_event_queue *q)
636 struct ssam_event_item *item;
639 item = list_first_entry_or_null(&q->head, struct ssam_event_item, node);
641 list_del(&item->node);
642 spin_unlock(&q->lock);
648 * ssam_event_queue_is_empty() - Check if the event queue is empty.
649 * @q: The event queue.
651 static bool ssam_event_queue_is_empty(struct ssam_event_queue *q)
656 empty = list_empty(&q->head);
657 spin_unlock(&q->lock);
663 * ssam_cplt_get_event_queue() - Get the event queue for the given parameters.
664 * @cplt: The completion system on which to look for the queue.
665 * @tid: The target ID of the queue.
666 * @rqid: The request ID representing the event ID for which to get the queue.
668 * Return: Returns the event queue corresponding to the event type described
669 * by the given parameters. If the request ID does not represent an event,
670 * this function returns %NULL. If the target ID is not supported, this
671 * function will fall back to the default target ID (``tid = 1``).
674 struct ssam_event_queue *ssam_cplt_get_event_queue(struct ssam_cplt *cplt,
677 u16 event = ssh_rqid_to_event(rqid);
678 u16 tidx = ssh_tid_to_index(tid);
680 if (!ssh_rqid_is_event(rqid)) {
681 dev_err(cplt->dev, "event: unsupported request ID: %#06x\n", rqid);
685 if (!ssh_tid_is_valid(tid)) {
686 dev_warn(cplt->dev, "event: unsupported target ID: %u\n", tid);
690 return &cplt->event.target[tidx].queue[event];
694 * ssam_cplt_submit() - Submit a work item to the completion system workqueue.
695 * @cplt: The completion system.
696 * @work: The work item to submit.
698 static bool ssam_cplt_submit(struct ssam_cplt *cplt, struct work_struct *work)
700 return queue_work(cplt->wq, work);
704 * ssam_cplt_submit_event() - Submit an event to the completion system.
705 * @cplt: The completion system.
706 * @item: The event item to submit.
708 * Submits the event to the completion system by queuing it on the event item
709 * queue and queuing the respective event queue work item on the completion
710 * workqueue, which will eventually complete the event.
712 * Return: Returns zero on success, %-EINVAL if there is no event queue that
713 * can handle the given event item.
715 static int ssam_cplt_submit_event(struct ssam_cplt *cplt,
716 struct ssam_event_item *item)
718 struct ssam_event_queue *evq;
720 evq = ssam_cplt_get_event_queue(cplt, item->event.target_id, item->rqid);
724 ssam_event_queue_push(evq, item);
725 ssam_cplt_submit(cplt, &evq->work);
730 * ssam_cplt_flush() - Flush the completion system.
731 * @cplt: The completion system.
733 * Flush the completion system by waiting until all currently submitted work
734 * items have been completed.
736 * Note: This function does not guarantee that all events will have been
737 * handled once this call terminates. In case of a larger number of
738 * to-be-completed events, the event queue work function may re-schedule its
739 * work item, which this flush operation will ignore.
741 * This operation is only intended to, during normal operation prior to
742 * shutdown, try to complete most events and requests to get them out of the
743 * system while the system is still fully operational. It does not aim to
744 * provide any guarantee that all of them have been handled.
746 static void ssam_cplt_flush(struct ssam_cplt *cplt)
748 flush_workqueue(cplt->wq);
751 static void ssam_event_queue_work_fn(struct work_struct *work)
753 struct ssam_event_queue *queue;
754 struct ssam_event_item *item;
757 unsigned int iterations = SSAM_CPLT_WQ_BATCH;
759 queue = container_of(work, struct ssam_event_queue, work);
760 nf = &queue->cplt->event.notif;
761 dev = queue->cplt->dev;
763 /* Limit number of processed events to avoid livelocking. */
765 item = ssam_event_queue_pop(queue);
769 ssam_nf_call(nf, dev, item->rqid, &item->event);
770 ssam_event_item_free(item);
771 } while (--iterations);
773 if (!ssam_event_queue_is_empty(queue))
774 ssam_cplt_submit(queue->cplt, &queue->work);
778 * ssam_event_queue_init() - Initialize an event queue.
779 * @cplt: The completion system on which the queue resides.
780 * @evq: The event queue to initialize.
782 static void ssam_event_queue_init(struct ssam_cplt *cplt,
783 struct ssam_event_queue *evq)
786 spin_lock_init(&evq->lock);
787 INIT_LIST_HEAD(&evq->head);
788 INIT_WORK(&evq->work, ssam_event_queue_work_fn);
792 * ssam_cplt_init() - Initialize completion system.
793 * @cplt: The completion system to initialize.
794 * @dev: The device used for logging.
796 static int ssam_cplt_init(struct ssam_cplt *cplt, struct device *dev)
798 struct ssam_event_target *target;
803 cplt->wq = create_workqueue(SSAM_CPLT_WQ_NAME);
807 for (c = 0; c < ARRAY_SIZE(cplt->event.target); c++) {
808 target = &cplt->event.target[c];
810 for (i = 0; i < ARRAY_SIZE(target->queue); i++)
811 ssam_event_queue_init(cplt, &target->queue[i]);
814 status = ssam_nf_init(&cplt->event.notif);
816 destroy_workqueue(cplt->wq);
822 * ssam_cplt_destroy() - Deinitialize the completion system.
823 * @cplt: The completion system to deinitialize.
825 * Deinitialize the given completion system and ensure that all pending, i.e.
826 * yet-to-be-completed, event items and requests have been handled.
828 static void ssam_cplt_destroy(struct ssam_cplt *cplt)
831 * Note: destroy_workqueue ensures that all currently queued work will
832 * be fully completed and the workqueue drained. This means that this
833 * call will inherently also free any queued ssam_event_items, thus we
834 * don't have to take care of that here explicitly.
836 destroy_workqueue(cplt->wq);
837 ssam_nf_destroy(&cplt->event.notif);
841 /* -- Main SSAM device structures. ------------------------------------------ */
844 * ssam_controller_device() - Get the &struct device associated with this
846 * @c: The controller for which to get the device.
848 * Return: Returns the &struct device associated with this controller,
849 * providing its lower-level transport.
851 struct device *ssam_controller_device(struct ssam_controller *c)
853 return ssh_rtl_get_device(&c->rtl);
855 EXPORT_SYMBOL_GPL(ssam_controller_device);
857 static void __ssam_controller_release(struct kref *kref)
859 struct ssam_controller *ctrl = to_ssam_controller(kref, kref);
862 * The lock-call here is to satisfy lockdep. At this point we really
863 * expect this to be the last remaining reference to the controller.
864 * Anything else is a bug.
866 ssam_controller_lock(ctrl);
867 ssam_controller_destroy(ctrl);
868 ssam_controller_unlock(ctrl);
874 * ssam_controller_get() - Increment reference count of controller.
875 * @c: The controller.
877 * Return: Returns the controller provided as input.
879 struct ssam_controller *ssam_controller_get(struct ssam_controller *c)
885 EXPORT_SYMBOL_GPL(ssam_controller_get);
888 * ssam_controller_put() - Decrement reference count of controller.
889 * @c: The controller.
891 void ssam_controller_put(struct ssam_controller *c)
894 kref_put(&c->kref, __ssam_controller_release);
896 EXPORT_SYMBOL_GPL(ssam_controller_put);
899 * ssam_controller_statelock() - Lock the controller against state transitions.
900 * @c: The controller to lock.
902 * Lock the controller against state transitions. Holding this lock guarantees
903 * that the controller will not transition between states, i.e. if the
904 * controller is in state "started", when this lock has been acquired, it will
905 * remain in this state at least until the lock has been released.
907 * Multiple clients may concurrently hold this lock. In other words: The
908 * ``statelock`` functions represent the read-lock part of a r/w-semaphore.
909 * Actions causing state transitions of the controller must be executed while
910 * holding the write-part of this r/w-semaphore (see ssam_controller_lock()
911 * and ssam_controller_unlock() for that).
913 * See ssam_controller_stateunlock() for the corresponding unlock function.
915 void ssam_controller_statelock(struct ssam_controller *c)
919 EXPORT_SYMBOL_GPL(ssam_controller_statelock);
922 * ssam_controller_stateunlock() - Unlock controller state transitions.
923 * @c: The controller to unlock.
925 * See ssam_controller_statelock() for the corresponding lock function.
927 void ssam_controller_stateunlock(struct ssam_controller *c)
931 EXPORT_SYMBOL_GPL(ssam_controller_stateunlock);
934 * ssam_controller_lock() - Acquire the main controller lock.
935 * @c: The controller to lock.
937 * This lock must be held for any state transitions, including transition to
938 * suspend/resumed states and during shutdown. See ssam_controller_statelock()
939 * for more details on controller locking.
941 * See ssam_controller_unlock() for the corresponding unlock function.
943 void ssam_controller_lock(struct ssam_controller *c)
945 down_write(&c->lock);
949 * ssam_controller_unlock() - Release the main controller lock.
950 * @c: The controller to unlock.
952 * See ssam_controller_lock() for the corresponding lock function.
954 void ssam_controller_unlock(struct ssam_controller *c)
959 static void ssam_handle_event(struct ssh_rtl *rtl,
960 const struct ssh_command *cmd,
961 const struct ssam_span *data)
963 struct ssam_controller *ctrl = to_ssam_controller(rtl, rtl);
964 struct ssam_event_item *item;
966 item = ssam_event_item_alloc(data->len, GFP_KERNEL);
970 item->rqid = get_unaligned_le16(&cmd->rqid);
971 item->event.target_category = cmd->tc;
972 item->event.target_id = cmd->tid_in;
973 item->event.command_id = cmd->cid;
974 item->event.instance_id = cmd->iid;
975 memcpy(&item->event.data[0], data->ptr, data->len);
977 if (WARN_ON(ssam_cplt_submit_event(&ctrl->cplt, item)))
978 ssam_event_item_free(item);
981 static const struct ssh_rtl_ops ssam_rtl_ops = {
982 .handle_event = ssam_handle_event,
985 static bool ssam_notifier_is_empty(struct ssam_controller *ctrl);
986 static void ssam_notifier_unregister_all(struct ssam_controller *ctrl);
988 #define SSAM_SSH_DSM_REVISION 0
990 /* d5e383e1-d892-4a76-89fc-f6aaae7ed5b5 */
991 static const guid_t SSAM_SSH_DSM_GUID =
992 GUID_INIT(0xd5e383e1, 0xd892, 0x4a76,
993 0x89, 0xfc, 0xf6, 0xaa, 0xae, 0x7e, 0xd5, 0xb5);
996 SSH_DSM_FN_SSH_POWER_PROFILE = 0x05,
997 SSH_DSM_FN_SCREEN_ON_SLEEP_IDLE_TIMEOUT = 0x06,
998 SSH_DSM_FN_SCREEN_OFF_SLEEP_IDLE_TIMEOUT = 0x07,
999 SSH_DSM_FN_D3_CLOSES_HANDLE = 0x08,
1000 SSH_DSM_FN_SSH_BUFFER_SIZE = 0x09,
1003 static int ssam_dsm_get_functions(acpi_handle handle, u64 *funcs)
1005 union acpi_object *obj;
1012 * The _DSM function is only present on newer models. It is not
1013 * present on 5th and 6th generation devices (i.e. up to and including
1014 * Surface Pro 6, Surface Laptop 2, Surface Book 2).
1016 * If the _DSM is not present, indicate that no function is supported.
1017 * This will result in default values being set.
1019 if (!acpi_has_method(handle, "_DSM"))
1022 obj = acpi_evaluate_dsm_typed(handle, &SSAM_SSH_DSM_GUID,
1023 SSAM_SSH_DSM_REVISION, 0, NULL,
1028 for (i = 0; i < obj->buffer.length && i < 8; i++)
1029 mask |= (((u64)obj->buffer.pointer[i]) << (i * 8));
1038 static int ssam_dsm_load_u32(acpi_handle handle, u64 funcs, u64 func, u32 *ret)
1040 union acpi_object *obj;
1043 if (!(funcs & BIT(func)))
1044 return 0; /* Not supported, leave *ret at its default value */
1046 obj = acpi_evaluate_dsm_typed(handle, &SSAM_SSH_DSM_GUID,
1047 SSAM_SSH_DSM_REVISION, func, NULL,
1052 val = obj->integer.value;
1063 * ssam_controller_caps_load_from_acpi() - Load controller capabilities from
1065 * @handle: The handle of the ACPI controller/SSH device.
1066 * @caps: Where to store the capabilities in.
1068 * Initializes the given controller capabilities with default values, then
1069 * checks and, if the respective _DSM functions are available, loads the
1070 * actual capabilities from the _DSM.
1072 * Return: Returns zero on success, a negative error code on failure.
1075 int ssam_controller_caps_load_from_acpi(acpi_handle handle,
1076 struct ssam_controller_caps *caps)
1078 u32 d3_closes_handle = false;
1083 caps->ssh_power_profile = U32_MAX;
1084 caps->screen_on_sleep_idle_timeout = U32_MAX;
1085 caps->screen_off_sleep_idle_timeout = U32_MAX;
1086 caps->d3_closes_handle = false;
1087 caps->ssh_buffer_size = U32_MAX;
1089 /* Pre-load supported DSM functions. */
1090 status = ssam_dsm_get_functions(handle, &funcs);
1094 /* Load actual values from ACPI, if present. */
1095 status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_SSH_POWER_PROFILE,
1096 &caps->ssh_power_profile);
1100 status = ssam_dsm_load_u32(handle, funcs,
1101 SSH_DSM_FN_SCREEN_ON_SLEEP_IDLE_TIMEOUT,
1102 &caps->screen_on_sleep_idle_timeout);
1106 status = ssam_dsm_load_u32(handle, funcs,
1107 SSH_DSM_FN_SCREEN_OFF_SLEEP_IDLE_TIMEOUT,
1108 &caps->screen_off_sleep_idle_timeout);
1112 status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_D3_CLOSES_HANDLE,
1117 caps->d3_closes_handle = !!d3_closes_handle;
1119 status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_SSH_BUFFER_SIZE,
1120 &caps->ssh_buffer_size);
1128 * ssam_controller_init() - Initialize SSAM controller.
1129 * @ctrl: The controller to initialize.
1130 * @serdev: The serial device representing the underlying data transport.
1132 * Initializes the given controller. Does neither start receiver nor
1133 * transmitter threads. After this call, the controller has to be hooked up to
1134 * the serdev core separately via &struct serdev_device_ops, relaying calls to
1135 * ssam_controller_receive_buf() and ssam_controller_write_wakeup(). Once the
1136 * controller has been hooked up, transmitter and receiver threads may be
1137 * started via ssam_controller_start(). These setup steps need to be completed
1138 * before controller can be used for requests.
1140 int ssam_controller_init(struct ssam_controller *ctrl,
1141 struct serdev_device *serdev)
1143 acpi_handle handle = ACPI_HANDLE(&serdev->dev);
1146 init_rwsem(&ctrl->lock);
1147 kref_init(&ctrl->kref);
1149 status = ssam_controller_caps_load_from_acpi(handle, &ctrl->caps);
1153 dev_dbg(&serdev->dev,
1154 "device capabilities:\n"
1155 " ssh_power_profile: %u\n"
1156 " ssh_buffer_size: %u\n"
1157 " screen_on_sleep_idle_timeout: %u\n"
1158 " screen_off_sleep_idle_timeout: %u\n"
1159 " d3_closes_handle: %u\n",
1160 ctrl->caps.ssh_power_profile,
1161 ctrl->caps.ssh_buffer_size,
1162 ctrl->caps.screen_on_sleep_idle_timeout,
1163 ctrl->caps.screen_off_sleep_idle_timeout,
1164 ctrl->caps.d3_closes_handle);
1166 ssh_seq_reset(&ctrl->counter.seq);
1167 ssh_rqid_reset(&ctrl->counter.rqid);
1169 /* Initialize event/request completion system. */
1170 status = ssam_cplt_init(&ctrl->cplt, &serdev->dev);
1174 /* Initialize request and packet transport layers. */
1175 status = ssh_rtl_init(&ctrl->rtl, serdev, &ssam_rtl_ops);
1177 ssam_cplt_destroy(&ctrl->cplt);
1182 * Set state via write_once even though we expect to be in an
1183 * exclusive context, due to smoke-testing in
1184 * ssam_request_sync_submit().
1186 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_INITIALIZED);
1191 * ssam_controller_start() - Start the receiver and transmitter threads of the
1193 * @ctrl: The controller.
1195 * Note: When this function is called, the controller should be properly
1196 * hooked up to the serdev core via &struct serdev_device_ops. Please refer
1197 * to ssam_controller_init() for more details on controller initialization.
1199 * This function must be called with the main controller lock held (i.e. by
1200 * calling ssam_controller_lock()).
1202 int ssam_controller_start(struct ssam_controller *ctrl)
1206 lockdep_assert_held_write(&ctrl->lock);
1208 if (ctrl->state != SSAM_CONTROLLER_INITIALIZED)
1211 status = ssh_rtl_start(&ctrl->rtl);
1216 * Set state via write_once even though we expect to be locked/in an
1217 * exclusive context, due to smoke-testing in
1218 * ssam_request_sync_submit().
1220 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STARTED);
1225 * SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT - Timeout for flushing requests during
1228 * Chosen to be larger than one full request timeout, including packets timing
1229 * out. This value should give ample time to complete any outstanding requests
1230 * during normal operation and account for the odd package timeout.
1232 #define SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT msecs_to_jiffies(5000)
1235 * ssam_controller_shutdown() - Shut down the controller.
1236 * @ctrl: The controller.
1238 * Shuts down the controller by flushing all pending requests and stopping the
1239 * transmitter and receiver threads. All requests submitted after this call
1240 * will fail with %-ESHUTDOWN. While it is discouraged to do so, this function
1241 * is safe to use in parallel with ongoing request submission.
1243 * In the course of this shutdown procedure, all currently registered
1244 * notifiers will be unregistered. It is, however, strongly recommended to not
1245 * rely on this behavior, and instead the party registering the notifier
1246 * should unregister it before the controller gets shut down, e.g. via the
1247 * SSAM bus which guarantees client devices to be removed before a shutdown.
1249 * Note that events may still be pending after this call, but, due to the
1250 * notifiers being unregistered, these events will be dropped when the
1251 * controller is subsequently destroyed via ssam_controller_destroy().
1253 * This function must be called with the main controller lock held (i.e. by
1254 * calling ssam_controller_lock()).
1256 void ssam_controller_shutdown(struct ssam_controller *ctrl)
1258 enum ssam_controller_state s = ctrl->state;
1261 lockdep_assert_held_write(&ctrl->lock);
1263 if (s == SSAM_CONTROLLER_UNINITIALIZED || s == SSAM_CONTROLLER_STOPPED)
1267 * Try to flush pending events and requests while everything still
1268 * works. Note: There may still be packets and/or requests in the
1269 * system after this call (e.g. via control packets submitted by the
1270 * packet transport layer or flush timeout / failure, ...). Those will
1271 * be handled with the ssh_rtl_shutdown() call below.
1273 status = ssh_rtl_flush(&ctrl->rtl, SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT);
1275 ssam_err(ctrl, "failed to flush request transport layer: %d\n",
1279 /* Try to flush all currently completing requests and events. */
1280 ssam_cplt_flush(&ctrl->cplt);
1283 * We expect all notifiers to have been removed by the respective client
1284 * driver that set them up at this point. If this warning occurs, some
1285 * client driver has not done that...
1287 WARN_ON(!ssam_notifier_is_empty(ctrl));
1290 * Nevertheless, we should still take care of drivers that don't behave
1291 * well. Thus disable all enabled events, unregister all notifiers.
1293 ssam_notifier_unregister_all(ctrl);
1296 * Cancel remaining requests. Ensure no new ones can be queued and stop
1299 ssh_rtl_shutdown(&ctrl->rtl);
1302 * Set state via write_once even though we expect to be locked/in an
1303 * exclusive context, due to smoke-testing in
1304 * ssam_request_sync_submit().
1306 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STOPPED);
1307 ctrl->rtl.ptl.serdev = NULL;
1311 * ssam_controller_destroy() - Destroy the controller and free its resources.
1312 * @ctrl: The controller.
1314 * Ensures that all resources associated with the controller get freed. This
1315 * function should only be called after the controller has been stopped via
1316 * ssam_controller_shutdown(). In general, this function should not be called
1317 * directly. The only valid place to call this function directly is during
1318 * initialization, before the controller has been fully initialized and passed
1319 * to other processes. This function is called automatically when the
1320 * reference count of the controller reaches zero.
1322 * This function must be called with the main controller lock held (i.e. by
1323 * calling ssam_controller_lock()).
1325 void ssam_controller_destroy(struct ssam_controller *ctrl)
1327 lockdep_assert_held_write(&ctrl->lock);
1329 if (ctrl->state == SSAM_CONTROLLER_UNINITIALIZED)
1332 WARN_ON(ctrl->state != SSAM_CONTROLLER_STOPPED);
1335 * Note: New events could still have been received after the previous
1336 * flush in ssam_controller_shutdown, before the request transport layer
1337 * has been shut down. At this point, after the shutdown, we can be sure
1338 * that no new events will be queued. The call to ssam_cplt_destroy will
1339 * ensure that those remaining are being completed and freed.
1342 /* Actually free resources. */
1343 ssam_cplt_destroy(&ctrl->cplt);
1344 ssh_rtl_destroy(&ctrl->rtl);
1347 * Set state via write_once even though we expect to be locked/in an
1348 * exclusive context, due to smoke-testing in
1349 * ssam_request_sync_submit().
1351 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_UNINITIALIZED);
1355 * ssam_controller_suspend() - Suspend the controller.
1356 * @ctrl: The controller to suspend.
1358 * Marks the controller as suspended. Note that display-off and D0-exit
1359 * notifications have to be sent manually before transitioning the controller
1360 * into the suspended state via this function.
1362 * See ssam_controller_resume() for the corresponding resume function.
1364 * Return: Returns %-EINVAL if the controller is currently not in the
1367 int ssam_controller_suspend(struct ssam_controller *ctrl)
1369 ssam_controller_lock(ctrl);
1371 if (ctrl->state != SSAM_CONTROLLER_STARTED) {
1372 ssam_controller_unlock(ctrl);
1376 ssam_dbg(ctrl, "pm: suspending controller\n");
1379 * Set state via write_once even though we're locked, due to
1380 * smoke-testing in ssam_request_sync_submit().
1382 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_SUSPENDED);
1384 ssam_controller_unlock(ctrl);
1389 * ssam_controller_resume() - Resume the controller from suspend.
1390 * @ctrl: The controller to resume.
1392 * Resume the controller from the suspended state it was put into via
1393 * ssam_controller_suspend(). This function does not issue display-on and
1394 * D0-entry notifications. If required, those have to be sent manually after
1397 * Return: Returns %-EINVAL if the controller is currently not suspended.
1399 int ssam_controller_resume(struct ssam_controller *ctrl)
1401 ssam_controller_lock(ctrl);
1403 if (ctrl->state != SSAM_CONTROLLER_SUSPENDED) {
1404 ssam_controller_unlock(ctrl);
1408 ssam_dbg(ctrl, "pm: resuming controller\n");
1411 * Set state via write_once even though we're locked, due to
1412 * smoke-testing in ssam_request_sync_submit().
1414 WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STARTED);
1416 ssam_controller_unlock(ctrl);
1421 /* -- Top-level request interface ------------------------------------------- */
1424 * ssam_request_write_data() - Construct and write SAM request message to
1426 * @buf: The buffer to write the data to.
1427 * @ctrl: The controller via which the request will be sent.
1428 * @spec: The request data and specification.
1430 * Constructs a SAM/SSH request message and writes it to the provided buffer.
1431 * The request and transport counters, specifically RQID and SEQ, will be set
1432 * in this call. These counters are obtained from the controller. It is thus
1433 * only valid to send the resulting message via the controller specified here.
1435 * For calculation of the required buffer size, refer to the
1436 * SSH_COMMAND_MESSAGE_LENGTH() macro.
1438 * Return: Returns the number of bytes used in the buffer on success. Returns
1439 * %-EINVAL if the payload length provided in the request specification is too
1440 * large (larger than %SSH_COMMAND_MAX_PAYLOAD_SIZE) or if the provided buffer
1443 ssize_t ssam_request_write_data(struct ssam_span *buf,
1444 struct ssam_controller *ctrl,
1445 const struct ssam_request *spec)
1451 if (spec->length > SSH_COMMAND_MAX_PAYLOAD_SIZE)
1454 if (SSH_COMMAND_MESSAGE_LENGTH(spec->length) > buf->len)
1457 msgb_init(&msgb, buf->ptr, buf->len);
1458 seq = ssh_seq_next(&ctrl->counter.seq);
1459 rqid = ssh_rqid_next(&ctrl->counter.rqid);
1460 msgb_push_cmd(&msgb, seq, rqid, spec);
1462 return msgb_bytes_used(&msgb);
1464 EXPORT_SYMBOL_GPL(ssam_request_write_data);
1466 static void ssam_request_sync_complete(struct ssh_request *rqst,
1467 const struct ssh_command *cmd,
1468 const struct ssam_span *data, int status)
1470 struct ssh_rtl *rtl = ssh_request_rtl(rqst);
1471 struct ssam_request_sync *r;
1473 r = container_of(rqst, struct ssam_request_sync, base);
1477 r->resp->length = 0;
1480 rtl_dbg_cond(rtl, "rsp: request failed: %d\n", status);
1484 if (!data) /* Handle requests without a response. */
1487 if (!r->resp || !r->resp->pointer) {
1489 rtl_warn(rtl, "rsp: no response buffer provided, dropping data\n");
1493 if (data->len > r->resp->capacity) {
1495 "rsp: response buffer too small, capacity: %zu bytes, got: %zu bytes\n",
1496 r->resp->capacity, data->len);
1497 r->status = -ENOSPC;
1501 r->resp->length = data->len;
1502 memcpy(r->resp->pointer, data->ptr, data->len);
1505 static void ssam_request_sync_release(struct ssh_request *rqst)
1507 complete_all(&container_of(rqst, struct ssam_request_sync, base)->comp);
1510 static const struct ssh_request_ops ssam_request_sync_ops = {
1511 .release = ssam_request_sync_release,
1512 .complete = ssam_request_sync_complete,
1516 * ssam_request_sync_alloc() - Allocate a synchronous request.
1517 * @payload_len: The length of the request payload.
1518 * @flags: Flags used for allocation.
1519 * @rqst: Where to store the pointer to the allocated request.
1520 * @buffer: Where to store the buffer descriptor for the message buffer of
1523 * Allocates a synchronous request with corresponding message buffer. The
1524 * request still needs to be initialized ssam_request_sync_init() before
1525 * it can be submitted, and the message buffer data must still be set to the
1526 * returned buffer via ssam_request_sync_set_data() after it has been filled,
1527 * if need be with adjusted message length.
1529 * After use, the request and its corresponding message buffer should be freed
1530 * via ssam_request_sync_free(). The buffer must not be freed separately.
1532 * Return: Returns zero on success, %-ENOMEM if the request could not be
1535 int ssam_request_sync_alloc(size_t payload_len, gfp_t flags,
1536 struct ssam_request_sync **rqst,
1537 struct ssam_span *buffer)
1539 size_t msglen = SSH_COMMAND_MESSAGE_LENGTH(payload_len);
1541 *rqst = kzalloc(sizeof(**rqst) + msglen, flags);
1545 buffer->ptr = (u8 *)(*rqst + 1);
1546 buffer->len = msglen;
1550 EXPORT_SYMBOL_GPL(ssam_request_sync_alloc);
1553 * ssam_request_sync_free() - Free a synchronous request.
1554 * @rqst: The request to be freed.
1556 * Free a synchronous request and its corresponding buffer allocated with
1557 * ssam_request_sync_alloc(). Do not use for requests allocated on the stack
1558 * or via any other function.
1560 * Warning: The caller must ensure that the request is not in use any more.
1561 * I.e. the caller must ensure that it has the only reference to the request
1562 * and the request is not currently pending. This means that the caller has
1563 * either never submitted the request, request submission has failed, or the
1564 * caller has waited until the submitted request has been completed via
1565 * ssam_request_sync_wait().
1567 void ssam_request_sync_free(struct ssam_request_sync *rqst)
1571 EXPORT_SYMBOL_GPL(ssam_request_sync_free);
1574 * ssam_request_sync_init() - Initialize a synchronous request struct.
1575 * @rqst: The request to initialize.
1576 * @flags: The request flags.
1578 * Initializes the given request struct. Does not initialize the request
1579 * message data. This has to be done explicitly after this call via
1580 * ssam_request_sync_set_data() and the actual message data has to be written
1581 * via ssam_request_write_data().
1583 * Return: Returns zero on success or %-EINVAL if the given flags are invalid.
1585 int ssam_request_sync_init(struct ssam_request_sync *rqst,
1586 enum ssam_request_flags flags)
1590 status = ssh_request_init(&rqst->base, flags, &ssam_request_sync_ops);
1594 init_completion(&rqst->comp);
1600 EXPORT_SYMBOL_GPL(ssam_request_sync_init);
1603 * ssam_request_sync_submit() - Submit a synchronous request.
1604 * @ctrl: The controller with which to submit the request.
1605 * @rqst: The request to submit.
1607 * Submit a synchronous request. The request has to be initialized and
1608 * properly set up, including response buffer (may be %NULL if no response is
1609 * expected) and command message data. This function does not wait for the
1610 * request to be completed.
1612 * If this function succeeds, ssam_request_sync_wait() must be used to ensure
1613 * that the request has been completed before the response data can be
1614 * accessed and/or the request can be freed. On failure, the request may
1615 * immediately be freed.
1617 * This function may only be used if the controller is active, i.e. has been
1618 * initialized and not suspended.
1620 int ssam_request_sync_submit(struct ssam_controller *ctrl,
1621 struct ssam_request_sync *rqst)
1626 * This is only a superficial check. In general, the caller needs to
1627 * ensure that the controller is initialized and is not (and does not
1628 * get) suspended during use, i.e. until the request has been completed
1629 * (if _absolutely_ necessary, by use of ssam_controller_statelock/
1630 * ssam_controller_stateunlock, but something like ssam_client_link
1631 * should be preferred as this needs to last until the request has been
1634 * Note that it is actually safe to use this function while the
1635 * controller is in the process of being shut down (as ssh_rtl_submit
1636 * is safe with regards to this), but it is generally discouraged to do
1639 if (WARN_ON(READ_ONCE(ctrl->state) != SSAM_CONTROLLER_STARTED)) {
1640 ssh_request_put(&rqst->base);
1644 status = ssh_rtl_submit(&ctrl->rtl, &rqst->base);
1645 ssh_request_put(&rqst->base);
1649 EXPORT_SYMBOL_GPL(ssam_request_sync_submit);
1652 * ssam_request_sync() - Execute a synchronous request.
1653 * @ctrl: The controller via which the request will be submitted.
1654 * @spec: The request specification and payload.
1655 * @rsp: The response buffer.
1657 * Allocates a synchronous request with its message data buffer on the heap
1658 * via ssam_request_sync_alloc(), fully initializes it via the provided
1659 * request specification, submits it, and finally waits for its completion
1660 * before freeing it and returning its status.
1662 * Return: Returns the status of the request or any failure during setup.
1664 int ssam_request_sync(struct ssam_controller *ctrl,
1665 const struct ssam_request *spec,
1666 struct ssam_response *rsp)
1668 struct ssam_request_sync *rqst;
1669 struct ssam_span buf;
1673 status = ssam_request_sync_alloc(spec->length, GFP_KERNEL, &rqst, &buf);
1677 status = ssam_request_sync_init(rqst, spec->flags);
1681 ssam_request_sync_set_resp(rqst, rsp);
1683 len = ssam_request_write_data(&buf, ctrl, spec);
1685 ssam_request_sync_free(rqst);
1689 ssam_request_sync_set_data(rqst, buf.ptr, len);
1691 status = ssam_request_sync_submit(ctrl, rqst);
1693 status = ssam_request_sync_wait(rqst);
1695 ssam_request_sync_free(rqst);
1698 EXPORT_SYMBOL_GPL(ssam_request_sync);
1701 * ssam_request_sync_with_buffer() - Execute a synchronous request with the
1702 * provided buffer as back-end for the message buffer.
1703 * @ctrl: The controller via which the request will be submitted.
1704 * @spec: The request specification and payload.
1705 * @rsp: The response buffer.
1706 * @buf: The buffer for the request message data.
1708 * Allocates a synchronous request struct on the stack, fully initializes it
1709 * using the provided buffer as message data buffer, submits it, and then
1710 * waits for its completion before returning its status. The
1711 * SSH_COMMAND_MESSAGE_LENGTH() macro can be used to compute the required
1712 * message buffer size.
1714 * This function does essentially the same as ssam_request_sync(), but instead
1715 * of dynamically allocating the request and message data buffer, it uses the
1716 * provided message data buffer and stores the (small) request struct on the
1719 * Return: Returns the status of the request or any failure during setup.
1721 int ssam_request_sync_with_buffer(struct ssam_controller *ctrl,
1722 const struct ssam_request *spec,
1723 struct ssam_response *rsp,
1724 struct ssam_span *buf)
1726 struct ssam_request_sync rqst;
1730 status = ssam_request_sync_init(&rqst, spec->flags);
1734 ssam_request_sync_set_resp(&rqst, rsp);
1736 len = ssam_request_write_data(buf, ctrl, spec);
1740 ssam_request_sync_set_data(&rqst, buf->ptr, len);
1742 status = ssam_request_sync_submit(ctrl, &rqst);
1744 status = ssam_request_sync_wait(&rqst);
1748 EXPORT_SYMBOL_GPL(ssam_request_sync_with_buffer);
1751 /* -- Internal SAM requests. ------------------------------------------------ */
1753 static SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_get_firmware_version, __le32, {
1754 .target_category = SSAM_SSH_TC_SAM,
1757 .instance_id = 0x00,
1760 static SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_off, u8, {
1761 .target_category = SSAM_SSH_TC_SAM,
1764 .instance_id = 0x00,
1767 static SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_on, u8, {
1768 .target_category = SSAM_SSH_TC_SAM,
1771 .instance_id = 0x00,
1774 static SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_exit, u8, {
1775 .target_category = SSAM_SSH_TC_SAM,
1778 .instance_id = 0x00,
1781 static SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_entry, u8, {
1782 .target_category = SSAM_SSH_TC_SAM,
1785 .instance_id = 0x00,
1789 * struct ssh_notification_params - Command payload to enable/disable SSH
1791 * @target_category: The target category for which notifications should be
1793 * @flags: Flags determining how notifications are being sent.
1794 * @request_id: The request ID that is used to send these notifications.
1795 * @instance_id: The specific instance in the given target category for
1796 * which notifications should be enabled.
1798 struct ssh_notification_params {
1805 static_assert(sizeof(struct ssh_notification_params) == 5);
1807 static int __ssam_ssh_event_request(struct ssam_controller *ctrl,
1808 struct ssam_event_registry reg, u8 cid,
1809 struct ssam_event_id id, u8 flags)
1811 struct ssh_notification_params params;
1812 struct ssam_request rqst;
1813 struct ssam_response result;
1816 u16 rqid = ssh_tc_to_rqid(id.target_category);
1819 /* Only allow RQIDs that lie within the event spectrum. */
1820 if (!ssh_rqid_is_event(rqid))
1823 params.target_category = id.target_category;
1824 params.instance_id = id.instance;
1825 params.flags = flags;
1826 put_unaligned_le16(rqid, ¶ms.request_id);
1828 rqst.target_category = reg.target_category;
1829 rqst.target_id = reg.target_id;
1830 rqst.command_id = cid;
1831 rqst.instance_id = 0x00;
1832 rqst.flags = SSAM_REQUEST_HAS_RESPONSE;
1833 rqst.length = sizeof(params);
1834 rqst.payload = (u8 *)¶ms;
1836 result.capacity = sizeof(buf);
1838 result.pointer = &buf;
1840 status = ssam_retry(ssam_request_sync_onstack, ctrl, &rqst, &result,
1843 return status < 0 ? status : buf;
1847 * ssam_ssh_event_enable() - Enable SSH event.
1848 * @ctrl: The controller for which to enable the event.
1849 * @reg: The event registry describing what request to use for enabling and
1850 * disabling the event.
1851 * @id: The event identifier.
1852 * @flags: The event flags.
1854 * Enables the specified event on the EC. This function does not manage
1855 * reference counting of enabled events and is basically only a wrapper for
1856 * the raw EC request. If the specified event is already enabled, the EC will
1857 * ignore this request.
1859 * Return: Returns the status of the executed SAM request (zero on success and
1860 * negative on direct failure) or %-EPROTO if the request response indicates a
1863 static int ssam_ssh_event_enable(struct ssam_controller *ctrl,
1864 struct ssam_event_registry reg,
1865 struct ssam_event_id id, u8 flags)
1869 status = __ssam_ssh_event_request(ctrl, reg, reg.cid_enable, id, flags);
1871 if (status < 0 && status != -EINVAL) {
1873 "failed to enable event source (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1874 id.target_category, id.instance, reg.target_category);
1879 "unexpected result while enabling event source: %#04x (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1880 status, id.target_category, id.instance, reg.target_category);
1888 * ssam_ssh_event_disable() - Disable SSH event.
1889 * @ctrl: The controller for which to disable the event.
1890 * @reg: The event registry describing what request to use for enabling and
1891 * disabling the event (must be same as used when enabling the event).
1892 * @id: The event identifier.
1893 * @flags: The event flags (likely ignored for disabling of events).
1895 * Disables the specified event on the EC. This function does not manage
1896 * reference counting of enabled events and is basically only a wrapper for
1897 * the raw EC request. If the specified event is already disabled, the EC will
1898 * ignore this request.
1900 * Return: Returns the status of the executed SAM request (zero on success and
1901 * negative on direct failure) or %-EPROTO if the request response indicates a
1904 static int ssam_ssh_event_disable(struct ssam_controller *ctrl,
1905 struct ssam_event_registry reg,
1906 struct ssam_event_id id, u8 flags)
1910 status = __ssam_ssh_event_request(ctrl, reg, reg.cid_enable, id, flags);
1912 if (status < 0 && status != -EINVAL) {
1914 "failed to disable event source (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1915 id.target_category, id.instance, reg.target_category);
1920 "unexpected result while disabling event source: %#04x (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1921 status, id.target_category, id.instance, reg.target_category);
1929 /* -- Wrappers for internal SAM requests. ----------------------------------- */
1932 * ssam_get_firmware_version() - Get the SAM/EC firmware version.
1933 * @ctrl: The controller.
1934 * @version: Where to store the version number.
1936 * Return: Returns zero on success or the status of the executed SAM request
1937 * if that request failed.
1939 int ssam_get_firmware_version(struct ssam_controller *ctrl, u32 *version)
1944 status = ssam_retry(ssam_ssh_get_firmware_version, ctrl, &__version);
1948 *version = le32_to_cpu(__version);
1953 * ssam_ctrl_notif_display_off() - Notify EC that the display has been turned
1955 * @ctrl: The controller.
1957 * Notify the EC that the display has been turned off and the driver may enter
1958 * a lower-power state. This will prevent events from being sent directly.
1959 * Rather, the EC signals an event by pulling the wakeup GPIO high for as long
1960 * as there are pending events. The events then need to be manually released,
1961 * one by one, via the GPIO callback request. All pending events accumulated
1962 * during this state can also be released by issuing the display-on
1963 * notification, e.g. via ssam_ctrl_notif_display_on(), which will also reset
1966 * On some devices, specifically ones with an integrated keyboard, the keyboard
1967 * backlight will be turned off by this call.
1969 * This function will only send the display-off notification command if
1970 * display notifications are supported by the EC. Currently all known devices
1971 * support these notifications.
1973 * Use ssam_ctrl_notif_display_on() to reverse the effects of this function.
1975 * Return: Returns zero on success or if no request has been executed, the
1976 * status of the executed SAM request if that request failed, or %-EPROTO if
1977 * an unexpected response has been received.
1979 int ssam_ctrl_notif_display_off(struct ssam_controller *ctrl)
1984 ssam_dbg(ctrl, "pm: notifying display off\n");
1986 status = ssam_retry(ssam_ssh_notif_display_off, ctrl, &response);
1990 if (response != 0) {
1991 ssam_err(ctrl, "unexpected response from display-off notification: %#04x\n",
2000 * ssam_ctrl_notif_display_on() - Notify EC that the display has been turned on.
2001 * @ctrl: The controller.
2003 * Notify the EC that the display has been turned back on and the driver has
2004 * exited its lower-power state. This notification is the counterpart to the
2005 * display-off notification sent via ssam_ctrl_notif_display_off() and will
2006 * reverse its effects, including resetting events to their default behavior.
2008 * This function will only send the display-on notification command if display
2009 * notifications are supported by the EC. Currently all known devices support
2010 * these notifications.
2012 * See ssam_ctrl_notif_display_off() for more details.
2014 * Return: Returns zero on success or if no request has been executed, the
2015 * status of the executed SAM request if that request failed, or %-EPROTO if
2016 * an unexpected response has been received.
2018 int ssam_ctrl_notif_display_on(struct ssam_controller *ctrl)
2023 ssam_dbg(ctrl, "pm: notifying display on\n");
2025 status = ssam_retry(ssam_ssh_notif_display_on, ctrl, &response);
2029 if (response != 0) {
2030 ssam_err(ctrl, "unexpected response from display-on notification: %#04x\n",
2039 * ssam_ctrl_notif_d0_exit() - Notify EC that the driver/device exits the D0
2041 * @ctrl: The controller
2043 * Notifies the EC that the driver prepares to exit the D0 power state in
2044 * favor of a lower-power state. Exact effects of this function related to the
2045 * EC are currently unknown.
2047 * This function will only send the D0-exit notification command if D0-state
2048 * notifications are supported by the EC. Only newer Surface generations
2049 * support these notifications.
2051 * Use ssam_ctrl_notif_d0_entry() to reverse the effects of this function.
2053 * Return: Returns zero on success or if no request has been executed, the
2054 * status of the executed SAM request if that request failed, or %-EPROTO if
2055 * an unexpected response has been received.
2057 int ssam_ctrl_notif_d0_exit(struct ssam_controller *ctrl)
2062 if (!ctrl->caps.d3_closes_handle)
2065 ssam_dbg(ctrl, "pm: notifying D0 exit\n");
2067 status = ssam_retry(ssam_ssh_notif_d0_exit, ctrl, &response);
2071 if (response != 0) {
2072 ssam_err(ctrl, "unexpected response from D0-exit notification: %#04x\n",
2081 * ssam_ctrl_notif_d0_entry() - Notify EC that the driver/device enters the D0
2083 * @ctrl: The controller
2085 * Notifies the EC that the driver has exited a lower-power state and entered
2086 * the D0 power state. Exact effects of this function related to the EC are
2087 * currently unknown.
2089 * This function will only send the D0-entry notification command if D0-state
2090 * notifications are supported by the EC. Only newer Surface generations
2091 * support these notifications.
2093 * See ssam_ctrl_notif_d0_exit() for more details.
2095 * Return: Returns zero on success or if no request has been executed, the
2096 * status of the executed SAM request if that request failed, or %-EPROTO if
2097 * an unexpected response has been received.
2099 int ssam_ctrl_notif_d0_entry(struct ssam_controller *ctrl)
2104 if (!ctrl->caps.d3_closes_handle)
2107 ssam_dbg(ctrl, "pm: notifying D0 entry\n");
2109 status = ssam_retry(ssam_ssh_notif_d0_entry, ctrl, &response);
2113 if (response != 0) {
2114 ssam_err(ctrl, "unexpected response from D0-entry notification: %#04x\n",
2123 /* -- Top-level event registry interface. ----------------------------------- */
2126 * ssam_notifier_register() - Register an event notifier.
2127 * @ctrl: The controller to register the notifier on.
2128 * @n: The event notifier to register.
2130 * Register an event notifier and increment the usage counter of the
2131 * associated SAM event. If the event was previously not enabled, it will be
2132 * enabled during this call.
2134 * Return: Returns zero on success, %-ENOSPC if there have already been
2135 * %INT_MAX notifiers for the event ID/type associated with the notifier block
2136 * registered, %-ENOMEM if the corresponding event entry could not be
2137 * allocated. If this is the first time that a notifier block is registered
2138 * for the specific associated event, returns the status of the event-enable
2141 int ssam_notifier_register(struct ssam_controller *ctrl,
2142 struct ssam_event_notifier *n)
2144 u16 rqid = ssh_tc_to_rqid(n->event.id.target_category);
2145 struct ssam_nf_refcount_entry *entry;
2146 struct ssam_nf_head *nf_head;
2150 if (!ssh_rqid_is_event(rqid))
2153 nf = &ctrl->cplt.event.notif;
2154 nf_head = &nf->head[ssh_rqid_to_event(rqid)];
2156 mutex_lock(&nf->lock);
2158 entry = ssam_nf_refcount_inc(nf, n->event.reg, n->event.id);
2159 if (IS_ERR(entry)) {
2160 mutex_unlock(&nf->lock);
2161 return PTR_ERR(entry);
2164 ssam_dbg(ctrl, "enabling event (reg: %#04x, tc: %#04x, iid: %#04x, rc: %d)\n",
2165 n->event.reg.target_category, n->event.id.target_category,
2166 n->event.id.instance, entry->refcount);
2168 status = ssam_nfblk_insert(nf_head, &n->base);
2170 entry = ssam_nf_refcount_dec(nf, n->event.reg, n->event.id);
2171 if (entry->refcount == 0)
2174 mutex_unlock(&nf->lock);
2178 if (entry->refcount == 1) {
2179 status = ssam_ssh_event_enable(ctrl, n->event.reg, n->event.id,
2182 ssam_nfblk_remove(&n->base);
2183 kfree(ssam_nf_refcount_dec(nf, n->event.reg, n->event.id));
2184 mutex_unlock(&nf->lock);
2185 synchronize_srcu(&nf_head->srcu);
2189 entry->flags = n->event.flags;
2191 } else if (entry->flags != n->event.flags) {
2193 "inconsistent flags when enabling event: got %#04x, expected %#04x (reg: %#04x, tc: %#04x, iid: %#04x)\n",
2194 n->event.flags, entry->flags, n->event.reg.target_category,
2195 n->event.id.target_category, n->event.id.instance);
2198 mutex_unlock(&nf->lock);
2201 EXPORT_SYMBOL_GPL(ssam_notifier_register);
2204 * ssam_notifier_unregister() - Unregister an event notifier.
2205 * @ctrl: The controller the notifier has been registered on.
2206 * @n: The event notifier to unregister.
2208 * Unregister an event notifier and decrement the usage counter of the
2209 * associated SAM event. If the usage counter reaches zero, the event will be
2212 * Return: Returns zero on success, %-ENOENT if the given notifier block has
2213 * not been registered on the controller. If the given notifier block was the
2214 * last one associated with its specific event, returns the status of the
2215 * event-disable EC-command.
2217 int ssam_notifier_unregister(struct ssam_controller *ctrl,
2218 struct ssam_event_notifier *n)
2220 u16 rqid = ssh_tc_to_rqid(n->event.id.target_category);
2221 struct ssam_nf_refcount_entry *entry;
2222 struct ssam_nf_head *nf_head;
2226 if (!ssh_rqid_is_event(rqid))
2229 nf = &ctrl->cplt.event.notif;
2230 nf_head = &nf->head[ssh_rqid_to_event(rqid)];
2232 mutex_lock(&nf->lock);
2234 if (!ssam_nfblk_find(nf_head, &n->base)) {
2235 mutex_unlock(&nf->lock);
2239 entry = ssam_nf_refcount_dec(nf, n->event.reg, n->event.id);
2240 if (WARN_ON(!entry)) {
2242 * If this does not return an entry, there's a logic error
2243 * somewhere: The notifier block is registered, but the event
2244 * refcount entry is not there. Remove the notifier block
2251 ssam_dbg(ctrl, "disabling event (reg: %#04x, tc: %#04x, iid: %#04x, rc: %d)\n",
2252 n->event.reg.target_category, n->event.id.target_category,
2253 n->event.id.instance, entry->refcount);
2255 if (entry->flags != n->event.flags) {
2257 "inconsistent flags when disabling event: got %#04x, expected %#04x (reg: %#04x, tc: %#04x, iid: %#04x)\n",
2258 n->event.flags, entry->flags, n->event.reg.target_category,
2259 n->event.id.target_category, n->event.id.instance);
2262 if (entry->refcount == 0) {
2263 status = ssam_ssh_event_disable(ctrl, n->event.reg, n->event.id,
2269 ssam_nfblk_remove(&n->base);
2270 mutex_unlock(&nf->lock);
2271 synchronize_srcu(&nf_head->srcu);
2275 EXPORT_SYMBOL_GPL(ssam_notifier_unregister);
2278 * ssam_notifier_disable_registered() - Disable events for all registered
2280 * @ctrl: The controller for which to disable the notifiers/events.
2282 * Disables events for all currently registered notifiers. In case of an error
2283 * (EC command failing), all previously disabled events will be restored and
2284 * the error code returned.
2286 * This function is intended to disable all events prior to hibernation entry.
2287 * See ssam_notifier_restore_registered() to restore/re-enable all events
2288 * disabled with this function.
2290 * Note that this function will not disable events for notifiers registered
2291 * after calling this function. It should thus be made sure that no new
2292 * notifiers are going to be added after this call and before the corresponding
2293 * call to ssam_notifier_restore_registered().
2295 * Return: Returns zero on success. In case of failure returns the error code
2296 * returned by the failed EC command to disable an event.
2298 int ssam_notifier_disable_registered(struct ssam_controller *ctrl)
2300 struct ssam_nf *nf = &ctrl->cplt.event.notif;
2304 mutex_lock(&nf->lock);
2305 for (n = rb_first(&nf->refcount); n; n = rb_next(n)) {
2306 struct ssam_nf_refcount_entry *e;
2308 e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2309 status = ssam_ssh_event_disable(ctrl, e->key.reg,
2310 e->key.id, e->flags);
2314 mutex_unlock(&nf->lock);
2319 for (n = rb_prev(n); n; n = rb_prev(n)) {
2320 struct ssam_nf_refcount_entry *e;
2322 e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2323 ssam_ssh_event_enable(ctrl, e->key.reg, e->key.id, e->flags);
2325 mutex_unlock(&nf->lock);
2331 * ssam_notifier_restore_registered() - Restore/re-enable events for all
2332 * registered notifiers.
2333 * @ctrl: The controller for which to restore the notifiers/events.
2335 * Restores/re-enables all events for which notifiers have been registered on
2336 * the given controller. In case of a failure, the error is logged and the
2337 * function continues to try and enable the remaining events.
2339 * This function is intended to restore/re-enable all registered events after
2340 * hibernation. See ssam_notifier_disable_registered() for the counter part
2341 * disabling the events and more details.
2343 void ssam_notifier_restore_registered(struct ssam_controller *ctrl)
2345 struct ssam_nf *nf = &ctrl->cplt.event.notif;
2348 mutex_lock(&nf->lock);
2349 for (n = rb_first(&nf->refcount); n; n = rb_next(n)) {
2350 struct ssam_nf_refcount_entry *e;
2352 e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2354 /* Ignore errors, will get logged in call. */
2355 ssam_ssh_event_enable(ctrl, e->key.reg, e->key.id, e->flags);
2357 mutex_unlock(&nf->lock);
2361 * ssam_notifier_is_empty() - Check if there are any registered notifiers.
2362 * @ctrl: The controller to check on.
2364 * Return: Returns %true if there are currently no notifiers registered on the
2365 * controller, %false otherwise.
2367 static bool ssam_notifier_is_empty(struct ssam_controller *ctrl)
2369 struct ssam_nf *nf = &ctrl->cplt.event.notif;
2372 mutex_lock(&nf->lock);
2373 result = ssam_nf_refcount_empty(nf);
2374 mutex_unlock(&nf->lock);
2380 * ssam_notifier_unregister_all() - Unregister all currently registered
2382 * @ctrl: The controller to unregister the notifiers on.
2384 * Unregisters all currently registered notifiers. This function is used to
2385 * ensure that all notifiers will be unregistered and associated
2386 * entries/resources freed when the controller is being shut down.
2388 static void ssam_notifier_unregister_all(struct ssam_controller *ctrl)
2390 struct ssam_nf *nf = &ctrl->cplt.event.notif;
2391 struct ssam_nf_refcount_entry *e, *n;
2393 mutex_lock(&nf->lock);
2394 rbtree_postorder_for_each_entry_safe(e, n, &nf->refcount, node) {
2395 /* Ignore errors, will get logged in call. */
2396 ssam_ssh_event_disable(ctrl, e->key.reg, e->key.id, e->flags);
2399 nf->refcount = RB_ROOT;
2400 mutex_unlock(&nf->lock);
2404 /* -- Wakeup IRQ. ----------------------------------------------------------- */
2406 static irqreturn_t ssam_irq_handle(int irq, void *dev_id)
2408 struct ssam_controller *ctrl = dev_id;
2410 ssam_dbg(ctrl, "pm: wake irq triggered\n");
2413 * Note: Proper wakeup detection is currently unimplemented.
2414 * When the EC is in display-off or any other non-D0 state, it
2415 * does not send events/notifications to the host. Instead it
2416 * signals that there are events available via the wakeup IRQ.
2417 * This driver is responsible for calling back to the EC to
2418 * release these events one-by-one.
2420 * This IRQ should not cause a full system resume by its own.
2421 * Instead, events should be handled by their respective subsystem
2422 * drivers, which in turn should signal whether a full system
2423 * resume should be performed.
2425 * TODO: Send GPIO callback command repeatedly to EC until callback
2426 * returns 0x00. Return flag of callback is "has more events".
2427 * Each time the command is sent, one event is "released". Once
2428 * all events have been released (return = 0x00), the GPIO is
2429 * re-armed. Detect wakeup events during this process, go back to
2430 * sleep if no wakeup event has been received.
2437 * ssam_irq_setup() - Set up SAM EC wakeup-GPIO interrupt.
2438 * @ctrl: The controller for which the IRQ should be set up.
2440 * Set up an IRQ for the wakeup-GPIO pin of the SAM EC. This IRQ can be used
2441 * to wake the device from a low power state.
2443 * Note that this IRQ can only be triggered while the EC is in the display-off
2444 * state. In this state, events are not sent to the host in the usual way.
2445 * Instead the wakeup-GPIO gets pulled to "high" as long as there are pending
2446 * events and these events need to be released one-by-one via the GPIO
2447 * callback request, either until there are no events left and the GPIO is
2448 * reset, or all at once by transitioning the EC out of the display-off state,
2449 * which will also clear the GPIO.
2451 * Not all events, however, should trigger a full system wakeup. Instead the
2452 * driver should, if necessary, inspect and forward each event to the
2453 * corresponding subsystem, which in turn should decide if the system needs to
2454 * be woken up. This logic has not been implemented yet, thus wakeup by this
2455 * IRQ should be disabled by default to avoid spurious wake-ups, caused, for
2456 * example, by the remaining battery percentage changing. Refer to comments in
2457 * this function and comments in the corresponding IRQ handler for more
2458 * details on how this should be implemented.
2460 * See also ssam_ctrl_notif_display_off() and ssam_ctrl_notif_display_off()
2461 * for functions to transition the EC into and out of the display-off state as
2462 * well as more details on it.
2464 * The IRQ is disabled by default and has to be enabled before it can wake up
2465 * the device from suspend via ssam_irq_arm_for_wakeup(). On teardown, the IRQ
2466 * should be freed via ssam_irq_free().
2468 int ssam_irq_setup(struct ssam_controller *ctrl)
2470 struct device *dev = ssam_controller_device(ctrl);
2471 struct gpio_desc *gpiod;
2476 * The actual GPIO interrupt is declared in ACPI as TRIGGER_HIGH.
2477 * However, the GPIO line only gets reset by sending the GPIO callback
2478 * command to SAM (or alternatively the display-on notification). As
2479 * proper handling for this interrupt is not implemented yet, leaving
2480 * the IRQ at TRIGGER_HIGH would cause an IRQ storm (as the callback
2481 * never gets sent and thus the line never gets reset). To avoid this,
2482 * mark the IRQ as TRIGGER_RISING for now, only creating a single
2483 * interrupt, and let the SAM resume callback during the controller
2484 * resume process clear it.
2486 const int irqf = IRQF_SHARED | IRQF_ONESHOT | IRQF_TRIGGER_RISING;
2488 gpiod = gpiod_get(dev, "ssam_wakeup-int", GPIOD_ASIS);
2490 return PTR_ERR(gpiod);
2492 irq = gpiod_to_irq(gpiod);
2498 status = request_threaded_irq(irq, NULL, ssam_irq_handle, irqf,
2499 "ssam_wakeup", ctrl);
2503 ctrl->irq.num = irq;
2504 disable_irq(ctrl->irq.num);
2509 * ssam_irq_free() - Free SAM EC wakeup-GPIO interrupt.
2510 * @ctrl: The controller for which the IRQ should be freed.
2512 * Free the wakeup-GPIO IRQ previously set-up via ssam_irq_setup().
2514 void ssam_irq_free(struct ssam_controller *ctrl)
2516 free_irq(ctrl->irq.num, ctrl);
2521 * ssam_irq_arm_for_wakeup() - Arm the EC IRQ for wakeup, if enabled.
2522 * @ctrl: The controller for which the IRQ should be armed.
2524 * Sets up the IRQ so that it can be used to wake the device. Specifically,
2525 * this function enables the irq and then, if the device is allowed to wake up
2526 * the system, calls enable_irq_wake(). See ssam_irq_disarm_wakeup() for the
2527 * corresponding function to disable the IRQ.
2529 * This function is intended to arm the IRQ before entering S2idle suspend.
2531 * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must
2534 int ssam_irq_arm_for_wakeup(struct ssam_controller *ctrl)
2536 struct device *dev = ssam_controller_device(ctrl);
2539 enable_irq(ctrl->irq.num);
2540 if (device_may_wakeup(dev)) {
2541 status = enable_irq_wake(ctrl->irq.num);
2543 ssam_err(ctrl, "failed to enable wake IRQ: %d\n", status);
2544 disable_irq(ctrl->irq.num);
2548 ctrl->irq.wakeup_enabled = true;
2550 ctrl->irq.wakeup_enabled = false;
2557 * ssam_irq_disarm_wakeup() - Disarm the wakeup IRQ.
2558 * @ctrl: The controller for which the IRQ should be disarmed.
2560 * Disarm the IRQ previously set up for wake via ssam_irq_arm_for_wakeup().
2562 * This function is intended to disarm the IRQ after exiting S2idle suspend.
2564 * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must
2567 void ssam_irq_disarm_wakeup(struct ssam_controller *ctrl)
2571 if (ctrl->irq.wakeup_enabled) {
2572 status = disable_irq_wake(ctrl->irq.num);
2574 ssam_err(ctrl, "failed to disable wake IRQ: %d\n", status);
2576 ctrl->irq.wakeup_enabled = false;
2578 disable_irq(ctrl->irq.num);