1 // SPDX-License-Identifier: GPL-2.0+
2 /*
3  * Main SSAM/SSH controller structure and functionality.
4  *
5  * Copyright (C) 2019-2022 Maximilian Luz <luzmaximilian@gmail.com>
6  */
7 
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>
27 
28 #include <linux/surface_aggregator/controller.h>
29 #include <linux/surface_aggregator/serial_hub.h>
30 
31 #include "controller.h"
32 #include "ssh_msgb.h"
33 #include "ssh_request_layer.h"
34 
35 #include "trace.h"
36 
37 
38 /* -- Safe counters. -------------------------------------------------------- */
39 
40 /**
41  * ssh_seq_reset() - Reset/initialize sequence ID counter.
42  * @c: The counter to reset.
43  */
44 static void ssh_seq_reset(struct ssh_seq_counter *c)
45 {
46 	WRITE_ONCE(c->value, 0);
47 }
48 
49 /**
50  * ssh_seq_next() - Get next sequence ID.
51  * @c: The counter providing the sequence IDs.
52  *
53  * Return: Returns the next sequence ID of the counter.
54  */
55 static u8 ssh_seq_next(struct ssh_seq_counter *c)
56 {
57 	u8 old = READ_ONCE(c->value);
58 	u8 new = old + 1;
59 	u8 ret;
60 
61 	while (unlikely((ret = cmpxchg(&c->value, old, new)) != old)) {
62 		old = ret;
63 		new = old + 1;
64 	}
65 
66 	return old;
67 }
68 
69 /**
70  * ssh_rqid_reset() - Reset/initialize request ID counter.
71  * @c: The counter to reset.
72  */
73 static void ssh_rqid_reset(struct ssh_rqid_counter *c)
74 {
75 	WRITE_ONCE(c->value, 0);
76 }
77 
78 /**
79  * ssh_rqid_next() - Get next request ID.
80  * @c: The counter providing the request IDs.
81  *
82  * Return: Returns the next request ID of the counter, skipping any reserved
83  * request IDs.
84  */
85 static u16 ssh_rqid_next(struct ssh_rqid_counter *c)
86 {
87 	u16 old = READ_ONCE(c->value);
88 	u16 new = ssh_rqid_next_valid(old);
89 	u16 ret;
90 
91 	while (unlikely((ret = cmpxchg(&c->value, old, new)) != old)) {
92 		old = ret;
93 		new = ssh_rqid_next_valid(old);
94 	}
95 
96 	return old;
97 }
98 
99 
100 /* -- Event notifier/callbacks. --------------------------------------------- */
101 /*
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.
108  */
109 
110 /**
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.
114  *
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.
117  */
118 static bool ssam_event_matches_notifier(const struct ssam_event_notifier *n,
119 					const struct ssam_event *event)
120 {
121 	bool match = n->event.id.target_category == event->target_category;
122 
123 	if (n->event.mask & SSAM_EVENT_MASK_TARGET)
124 		match &= n->event.reg.target_id == event->target_id;
125 
126 	if (n->event.mask & SSAM_EVENT_MASK_INSTANCE)
127 		match &= n->event.id.instance == event->instance_id;
128 
129 	return match;
130 }
131 
132 /**
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.
136  *
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.
141  *
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
146  * value.
147  */
148 static int ssam_nfblk_call_chain(struct ssam_nf_head *nh, struct ssam_event *event)
149 {
150 	struct ssam_event_notifier *nf;
151 	int ret = 0, idx;
152 
153 	idx = srcu_read_lock(&nh->srcu);
154 
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)
160 				break;
161 		}
162 	}
163 
164 	srcu_read_unlock(&nh->srcu, idx);
165 	return ret;
166 }
167 
168 /**
169  * ssam_nfblk_insert() - Insert a new notifier block into the given notifier
170  * list.
171  * @nh: The notifier head into which the block should be inserted.
172  * @nb: The notifier block to add.
173  *
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``.
176  *
177  * Return: Returns zero on success, %-EEXIST if the notifier block has already
178  * been registered.
179  */
180 static int ssam_nfblk_insert(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)
181 {
182 	struct ssam_notifier_block *p;
183 	struct list_head *h;
184 
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);
188 
189 		if (unlikely(p == nb)) {
190 			WARN(1, "double register detected");
191 			return -EEXIST;
192 		}
193 
194 		if (nb->priority > p->priority)
195 			break;
196 	}
197 
198 	list_add_tail_rcu(&nb->node, h);
199 	return 0;
200 }
201 
202 /**
203  * ssam_nfblk_find() - Check if a notifier block is registered on the given
204  * notifier head.
205  * list.
206  * @nh: The notifier head on which to search.
207  * @nb: The notifier block to search for.
208  *
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``.
211  *
212  * Return: Returns true if the given notifier block is registered on the given
213  * notifier head, false otherwise.
214  */
215 static bool ssam_nfblk_find(struct ssam_nf_head *nh, struct ssam_notifier_block *nb)
216 {
217 	struct ssam_notifier_block *p;
218 
219 	/* Runs under lock, no need for RCU variant. */
220 	list_for_each_entry(p, &nh->head, node) {
221 		if (p == nb)
222 			return true;
223 	}
224 
225 	return false;
226 }
227 
228 /**
229  * ssam_nfblk_remove() - Remove a notifier block from its notifier list.
230  * @nb: The notifier block to be removed.
231  *
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.
237  */
238 static void ssam_nfblk_remove(struct ssam_notifier_block *nb)
239 {
240 	list_del_rcu(&nb->node);
241 }
242 
243 /**
244  * ssam_nf_head_init() - Initialize the given notifier head.
245  * @nh: The notifier head to initialize.
246  */
247 static int ssam_nf_head_init(struct ssam_nf_head *nh)
248 {
249 	int status;
250 
251 	status = init_srcu_struct(&nh->srcu);
252 	if (status)
253 		return status;
254 
255 	INIT_LIST_HEAD(&nh->head);
256 	return 0;
257 }
258 
259 /**
260  * ssam_nf_head_destroy() - Deinitialize the given notifier head.
261  * @nh: The notifier head to deinitialize.
262  */
263 static void ssam_nf_head_destroy(struct ssam_nf_head *nh)
264 {
265 	cleanup_srcu_struct(&nh->srcu);
266 }
267 
268 
269 /* -- Event/notification registry. ------------------------------------------ */
270 
271 /**
272  * struct ssam_nf_refcount_key - Key used for event activation reference
273  * counting.
274  * @reg: The registry via which the event is enabled/disabled.
275  * @id:  The ID uniquely describing the event.
276  */
277 struct ssam_nf_refcount_key {
278 	struct ssam_event_registry reg;
279 	struct ssam_event_id id;
280 };
281 
282 /**
283  * struct ssam_nf_refcount_entry - RB-tree entry for reference counting event
284  * activations.
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.
289  */
290 struct ssam_nf_refcount_entry {
291 	struct rb_node node;
292 	struct ssam_nf_refcount_key key;
293 	int refcount;
294 	u8 flags;
295 };
296 
297 /**
298  * ssam_nf_refcount_inc() - Increment reference-/activation-count of the given
299  * event.
300  * @nf:  The notifier system reference.
301  * @reg: The registry used to enable/disable the event.
302  * @id:  The event ID.
303  *
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.
307  *
308  * Note: ``nf->lock`` must be held when calling this function.
309  *
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.
313  */
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)
317 {
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;
322 	int cmp;
323 
324 	lockdep_assert_held(&nf->lock);
325 
326 	key.reg = reg;
327 	key.id = id;
328 
329 	while (*link) {
330 		entry = rb_entry(*link, struct ssam_nf_refcount_entry, node);
331 		parent = *link;
332 
333 		cmp = memcmp(&key, &entry->key, sizeof(key));
334 		if (cmp < 0) {
335 			link = &(*link)->rb_left;
336 		} else if (cmp > 0) {
337 			link = &(*link)->rb_right;
338 		} else if (entry->refcount < INT_MAX) {
339 			entry->refcount++;
340 			return entry;
341 		} else {
342 			WARN_ON(1);
343 			return ERR_PTR(-ENOSPC);
344 		}
345 	}
346 
347 	entry = kzalloc(sizeof(*entry), GFP_KERNEL);
348 	if (!entry)
349 		return ERR_PTR(-ENOMEM);
350 
351 	entry->key = key;
352 	entry->refcount = 1;
353 
354 	rb_link_node(&entry->node, parent, link);
355 	rb_insert_color(&entry->node, &nf->refcount);
356 
357 	return entry;
358 }
359 
360 /**
361  * ssam_nf_refcount_dec() - Decrement reference-/activation-count of the given
362  * event.
363  * @nf:  The notifier system reference.
364  * @reg: The registry used to enable/disable the event.
365  * @id:  The event ID.
366  *
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().
370  *
371  * Note: ``nf->lock`` must be held when calling this function.
372  *
373  * Return: Returns the refcount entry on success or %NULL if the entry has not
374  * been found.
375  */
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)
379 {
380 	struct ssam_nf_refcount_entry *entry;
381 	struct ssam_nf_refcount_key key;
382 	struct rb_node *node = nf->refcount.rb_node;
383 	int cmp;
384 
385 	lockdep_assert_held(&nf->lock);
386 
387 	key.reg = reg;
388 	key.id = id;
389 
390 	while (node) {
391 		entry = rb_entry(node, struct ssam_nf_refcount_entry, node);
392 
393 		cmp = memcmp(&key, &entry->key, sizeof(key));
394 		if (cmp < 0) {
395 			node = node->rb_left;
396 		} else if (cmp > 0) {
397 			node = node->rb_right;
398 		} else {
399 			entry->refcount--;
400 			if (entry->refcount == 0)
401 				rb_erase(&entry->node, &nf->refcount);
402 
403 			return entry;
404 		}
405 	}
406 
407 	return NULL;
408 }
409 
410 /**
411  * ssam_nf_refcount_dec_free() - Decrement reference-/activation-count of the
412  * given event and free its entry if the reference count reaches zero.
413  * @nf:  The notifier system reference.
414  * @reg: The registry used to enable/disable the event.
415  * @id:  The event ID.
416  *
417  * Decrements the reference-/activation-count of the specified event, freeing
418  * its entry if it reaches zero.
419  *
420  * Note: ``nf->lock`` must be held when calling this function.
421  */
422 static void ssam_nf_refcount_dec_free(struct ssam_nf *nf,
423 				      struct ssam_event_registry reg,
424 				      struct ssam_event_id id)
425 {
426 	struct ssam_nf_refcount_entry *entry;
427 
428 	lockdep_assert_held(&nf->lock);
429 
430 	entry = ssam_nf_refcount_dec(nf, reg, id);
431 	if (entry && entry->refcount == 0)
432 		kfree(entry);
433 }
434 
435 /**
436  * ssam_nf_refcount_empty() - Test if the notification system has any
437  * enabled/active events.
438  * @nf: The notification system.
439  */
440 static bool ssam_nf_refcount_empty(struct ssam_nf *nf)
441 {
442 	return RB_EMPTY_ROOT(&nf->refcount);
443 }
444 
445 /**
446  * ssam_nf_call() - Call notification callbacks for the provided event.
447  * @nf:    The notifier system
448  * @dev:   The associated device, only used for logging.
449  * @rqid:  The request ID of the event.
450  * @event: The event provided to the callbacks.
451  *
452  * Execute registered callbacks in order of their priority until either no
453  * callback is left or a callback returns a value with the %SSAM_NOTIF_STOP
454  * bit set. Note that this bit is set automatically when converting non-zero
455  * error values via ssam_notifier_from_errno() to notifier values.
456  *
457  * Also note that any callback that could handle an event should return a value
458  * with bit %SSAM_NOTIF_HANDLED set, indicating that the event does not go
459  * unhandled/ignored. In case no registered callback could handle an event,
460  * this function will emit a warning.
461  *
462  * In case a callback failed, this function will emit an error message.
463  */
464 static void ssam_nf_call(struct ssam_nf *nf, struct device *dev, u16 rqid,
465 			 struct ssam_event *event)
466 {
467 	struct ssam_nf_head *nf_head;
468 	int status, nf_ret;
469 
470 	if (!ssh_rqid_is_event(rqid)) {
471 		dev_warn(dev, "event: unsupported rqid: %#06x\n", rqid);
472 		return;
473 	}
474 
475 	nf_head = &nf->head[ssh_rqid_to_event(rqid)];
476 	nf_ret = ssam_nfblk_call_chain(nf_head, event);
477 	status = ssam_notifier_to_errno(nf_ret);
478 
479 	if (status < 0) {
480 		dev_err(dev,
481 			"event: error handling event: %d (tc: %#04x, tid: %#04x, cid: %#04x, iid: %#04x)\n",
482 			status, event->target_category, event->target_id,
483 			event->command_id, event->instance_id);
484 	} else if (!(nf_ret & SSAM_NOTIF_HANDLED)) {
485 		dev_warn(dev,
486 			 "event: unhandled event (rqid: %#04x, tc: %#04x, tid: %#04x, cid: %#04x, iid: %#04x)\n",
487 			 rqid, event->target_category, event->target_id,
488 			 event->command_id, event->instance_id);
489 	}
490 }
491 
492 /**
493  * ssam_nf_init() - Initialize the notifier system.
494  * @nf: The notifier system to initialize.
495  */
496 static int ssam_nf_init(struct ssam_nf *nf)
497 {
498 	int i, status;
499 
500 	for (i = 0; i < SSH_NUM_EVENTS; i++) {
501 		status = ssam_nf_head_init(&nf->head[i]);
502 		if (status)
503 			break;
504 	}
505 
506 	if (status) {
507 		while (i--)
508 			ssam_nf_head_destroy(&nf->head[i]);
509 
510 		return status;
511 	}
512 
513 	mutex_init(&nf->lock);
514 	return 0;
515 }
516 
517 /**
518  * ssam_nf_destroy() - Deinitialize the notifier system.
519  * @nf: The notifier system to deinitialize.
520  */
521 static void ssam_nf_destroy(struct ssam_nf *nf)
522 {
523 	int i;
524 
525 	for (i = 0; i < SSH_NUM_EVENTS; i++)
526 		ssam_nf_head_destroy(&nf->head[i]);
527 
528 	mutex_destroy(&nf->lock);
529 }
530 
531 
532 /* -- Event/async request completion system. -------------------------------- */
533 
534 #define SSAM_CPLT_WQ_NAME	"ssam_cpltq"
535 
536 /*
537  * SSAM_CPLT_WQ_BATCH - Maximum number of event item completions executed per
538  * work execution. Used to prevent livelocking of the workqueue. Value chosen
539  * via educated guess, may be adjusted.
540  */
541 #define SSAM_CPLT_WQ_BATCH	10
542 
543 /*
544  * SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN - Maximum payload length for a cached
545  * &struct ssam_event_item.
546  *
547  * This length has been chosen to be accommodate standard touchpad and
548  * keyboard input events. Events with larger payloads will be allocated
549  * separately.
550  */
551 #define SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN	32
552 
553 static struct kmem_cache *ssam_event_item_cache;
554 
555 /**
556  * ssam_event_item_cache_init() - Initialize the event item cache.
557  */
558 int ssam_event_item_cache_init(void)
559 {
560 	const unsigned int size = sizeof(struct ssam_event_item)
561 				  + SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN;
562 	const unsigned int align = __alignof__(struct ssam_event_item);
563 	struct kmem_cache *cache;
564 
565 	cache = kmem_cache_create("ssam_event_item", size, align, 0, NULL);
566 	if (!cache)
567 		return -ENOMEM;
568 
569 	ssam_event_item_cache = cache;
570 	return 0;
571 }
572 
573 /**
574  * ssam_event_item_cache_destroy() - Deinitialize the event item cache.
575  */
576 void ssam_event_item_cache_destroy(void)
577 {
578 	kmem_cache_destroy(ssam_event_item_cache);
579 	ssam_event_item_cache = NULL;
580 }
581 
582 static void __ssam_event_item_free_cached(struct ssam_event_item *item)
583 {
584 	kmem_cache_free(ssam_event_item_cache, item);
585 }
586 
587 static void __ssam_event_item_free_generic(struct ssam_event_item *item)
588 {
589 	kfree(item);
590 }
591 
592 /**
593  * ssam_event_item_free() - Free the provided event item.
594  * @item: The event item to free.
595  */
596 static void ssam_event_item_free(struct ssam_event_item *item)
597 {
598 	trace_ssam_event_item_free(item);
599 	item->ops.free(item);
600 }
601 
602 /**
603  * ssam_event_item_alloc() - Allocate an event item with the given payload size.
604  * @len:   The event payload length.
605  * @flags: The flags used for allocation.
606  *
607  * Allocate an event item with the given payload size, preferring allocation
608  * from the event item cache if the payload is small enough (i.e. smaller than
609  * %SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN). Sets the item operations and payload
610  * length values. The item free callback (``ops.free``) should not be
611  * overwritten after this call.
612  *
613  * Return: Returns the newly allocated event item.
614  */
615 static struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags)
616 {
617 	struct ssam_event_item *item;
618 
619 	if (len <= SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN) {
620 		item = kmem_cache_alloc(ssam_event_item_cache, flags);
621 		if (!item)
622 			return NULL;
623 
624 		item->ops.free = __ssam_event_item_free_cached;
625 	} else {
626 		item = kzalloc(struct_size(item, event.data, len), flags);
627 		if (!item)
628 			return NULL;
629 
630 		item->ops.free = __ssam_event_item_free_generic;
631 	}
632 
633 	item->event.length = len;
634 
635 	trace_ssam_event_item_alloc(item, len);
636 	return item;
637 }
638 
639 /**
640  * ssam_event_queue_push() - Push an event item to the event queue.
641  * @q:    The event queue.
642  * @item: The item to add.
643  */
644 static void ssam_event_queue_push(struct ssam_event_queue *q,
645 				  struct ssam_event_item *item)
646 {
647 	spin_lock(&q->lock);
648 	list_add_tail(&item->node, &q->head);
649 	spin_unlock(&q->lock);
650 }
651 
652 /**
653  * ssam_event_queue_pop() - Pop the next event item from the event queue.
654  * @q: The event queue.
655  *
656  * Returns and removes the next event item from the queue. Returns %NULL If
657  * there is no event item left.
658  */
659 static struct ssam_event_item *ssam_event_queue_pop(struct ssam_event_queue *q)
660 {
661 	struct ssam_event_item *item;
662 
663 	spin_lock(&q->lock);
664 	item = list_first_entry_or_null(&q->head, struct ssam_event_item, node);
665 	if (item)
666 		list_del(&item->node);
667 	spin_unlock(&q->lock);
668 
669 	return item;
670 }
671 
672 /**
673  * ssam_event_queue_is_empty() - Check if the event queue is empty.
674  * @q: The event queue.
675  */
676 static bool ssam_event_queue_is_empty(struct ssam_event_queue *q)
677 {
678 	bool empty;
679 
680 	spin_lock(&q->lock);
681 	empty = list_empty(&q->head);
682 	spin_unlock(&q->lock);
683 
684 	return empty;
685 }
686 
687 /**
688  * ssam_cplt_get_event_queue() - Get the event queue for the given parameters.
689  * @cplt: The completion system on which to look for the queue.
690  * @tid:  The target ID of the queue.
691  * @rqid: The request ID representing the event ID for which to get the queue.
692  *
693  * Return: Returns the event queue corresponding to the event type described
694  * by the given parameters. If the request ID does not represent an event,
695  * this function returns %NULL. If the target ID is not supported, this
696  * function will fall back to the default target ID (``tid = 1``).
697  */
698 static
699 struct ssam_event_queue *ssam_cplt_get_event_queue(struct ssam_cplt *cplt,
700 						   u8 tid, u16 rqid)
701 {
702 	u16 event = ssh_rqid_to_event(rqid);
703 	u16 tidx = ssh_tid_to_index(tid);
704 
705 	if (!ssh_rqid_is_event(rqid)) {
706 		dev_err(cplt->dev, "event: unsupported request ID: %#06x\n", rqid);
707 		return NULL;
708 	}
709 
710 	if (!ssh_tid_is_valid(tid)) {
711 		dev_warn(cplt->dev, "event: unsupported target ID: %u\n", tid);
712 		tidx = 0;
713 	}
714 
715 	return &cplt->event.target[tidx].queue[event];
716 }
717 
718 /**
719  * ssam_cplt_submit() - Submit a work item to the completion system workqueue.
720  * @cplt: The completion system.
721  * @work: The work item to submit.
722  */
723 static bool ssam_cplt_submit(struct ssam_cplt *cplt, struct work_struct *work)
724 {
725 	return queue_work(cplt->wq, work);
726 }
727 
728 /**
729  * ssam_cplt_submit_event() - Submit an event to the completion system.
730  * @cplt: The completion system.
731  * @item: The event item to submit.
732  *
733  * Submits the event to the completion system by queuing it on the event item
734  * queue and queuing the respective event queue work item on the completion
735  * workqueue, which will eventually complete the event.
736  *
737  * Return: Returns zero on success, %-EINVAL if there is no event queue that
738  * can handle the given event item.
739  */
740 static int ssam_cplt_submit_event(struct ssam_cplt *cplt,
741 				  struct ssam_event_item *item)
742 {
743 	struct ssam_event_queue *evq;
744 
745 	evq = ssam_cplt_get_event_queue(cplt, item->event.target_id, item->rqid);
746 	if (!evq)
747 		return -EINVAL;
748 
749 	ssam_event_queue_push(evq, item);
750 	ssam_cplt_submit(cplt, &evq->work);
751 	return 0;
752 }
753 
754 /**
755  * ssam_cplt_flush() - Flush the completion system.
756  * @cplt: The completion system.
757  *
758  * Flush the completion system by waiting until all currently submitted work
759  * items have been completed.
760  *
761  * Note: This function does not guarantee that all events will have been
762  * handled once this call terminates. In case of a larger number of
763  * to-be-completed events, the event queue work function may re-schedule its
764  * work item, which this flush operation will ignore.
765  *
766  * This operation is only intended to, during normal operation prior to
767  * shutdown, try to complete most events and requests to get them out of the
768  * system while the system is still fully operational. It does not aim to
769  * provide any guarantee that all of them have been handled.
770  */
771 static void ssam_cplt_flush(struct ssam_cplt *cplt)
772 {
773 	flush_workqueue(cplt->wq);
774 }
775 
776 static void ssam_event_queue_work_fn(struct work_struct *work)
777 {
778 	struct ssam_event_queue *queue;
779 	struct ssam_event_item *item;
780 	struct ssam_nf *nf;
781 	struct device *dev;
782 	unsigned int iterations = SSAM_CPLT_WQ_BATCH;
783 
784 	queue = container_of(work, struct ssam_event_queue, work);
785 	nf = &queue->cplt->event.notif;
786 	dev = queue->cplt->dev;
787 
788 	/* Limit number of processed events to avoid livelocking. */
789 	do {
790 		item = ssam_event_queue_pop(queue);
791 		if (!item)
792 			return;
793 
794 		ssam_nf_call(nf, dev, item->rqid, &item->event);
795 		ssam_event_item_free(item);
796 	} while (--iterations);
797 
798 	if (!ssam_event_queue_is_empty(queue))
799 		ssam_cplt_submit(queue->cplt, &queue->work);
800 }
801 
802 /**
803  * ssam_event_queue_init() - Initialize an event queue.
804  * @cplt: The completion system on which the queue resides.
805  * @evq:  The event queue to initialize.
806  */
807 static void ssam_event_queue_init(struct ssam_cplt *cplt,
808 				  struct ssam_event_queue *evq)
809 {
810 	evq->cplt = cplt;
811 	spin_lock_init(&evq->lock);
812 	INIT_LIST_HEAD(&evq->head);
813 	INIT_WORK(&evq->work, ssam_event_queue_work_fn);
814 }
815 
816 /**
817  * ssam_cplt_init() - Initialize completion system.
818  * @cplt: The completion system to initialize.
819  * @dev:  The device used for logging.
820  */
821 static int ssam_cplt_init(struct ssam_cplt *cplt, struct device *dev)
822 {
823 	struct ssam_event_target *target;
824 	int status, c, i;
825 
826 	cplt->dev = dev;
827 
828 	cplt->wq = alloc_workqueue(SSAM_CPLT_WQ_NAME, WQ_UNBOUND | WQ_MEM_RECLAIM, 0);
829 	if (!cplt->wq)
830 		return -ENOMEM;
831 
832 	for (c = 0; c < ARRAY_SIZE(cplt->event.target); c++) {
833 		target = &cplt->event.target[c];
834 
835 		for (i = 0; i < ARRAY_SIZE(target->queue); i++)
836 			ssam_event_queue_init(cplt, &target->queue[i]);
837 	}
838 
839 	status = ssam_nf_init(&cplt->event.notif);
840 	if (status)
841 		destroy_workqueue(cplt->wq);
842 
843 	return status;
844 }
845 
846 /**
847  * ssam_cplt_destroy() - Deinitialize the completion system.
848  * @cplt: The completion system to deinitialize.
849  *
850  * Deinitialize the given completion system and ensure that all pending, i.e.
851  * yet-to-be-completed, event items and requests have been handled.
852  */
853 static void ssam_cplt_destroy(struct ssam_cplt *cplt)
854 {
855 	/*
856 	 * Note: destroy_workqueue ensures that all currently queued work will
857 	 * be fully completed and the workqueue drained. This means that this
858 	 * call will inherently also free any queued ssam_event_items, thus we
859 	 * don't have to take care of that here explicitly.
860 	 */
861 	destroy_workqueue(cplt->wq);
862 	ssam_nf_destroy(&cplt->event.notif);
863 }
864 
865 
866 /* -- Main SSAM device structures. ------------------------------------------ */
867 
868 /**
869  * ssam_controller_device() - Get the &struct device associated with this
870  * controller.
871  * @c: The controller for which to get the device.
872  *
873  * Return: Returns the &struct device associated with this controller,
874  * providing its lower-level transport.
875  */
876 struct device *ssam_controller_device(struct ssam_controller *c)
877 {
878 	return ssh_rtl_get_device(&c->rtl);
879 }
880 EXPORT_SYMBOL_GPL(ssam_controller_device);
881 
882 static void __ssam_controller_release(struct kref *kref)
883 {
884 	struct ssam_controller *ctrl = to_ssam_controller(kref, kref);
885 
886 	/*
887 	 * The lock-call here is to satisfy lockdep. At this point we really
888 	 * expect this to be the last remaining reference to the controller.
889 	 * Anything else is a bug.
890 	 */
891 	ssam_controller_lock(ctrl);
892 	ssam_controller_destroy(ctrl);
893 	ssam_controller_unlock(ctrl);
894 
895 	kfree(ctrl);
896 }
897 
898 /**
899  * ssam_controller_get() - Increment reference count of controller.
900  * @c: The controller.
901  *
902  * Return: Returns the controller provided as input.
903  */
904 struct ssam_controller *ssam_controller_get(struct ssam_controller *c)
905 {
906 	if (c)
907 		kref_get(&c->kref);
908 	return c;
909 }
910 EXPORT_SYMBOL_GPL(ssam_controller_get);
911 
912 /**
913  * ssam_controller_put() - Decrement reference count of controller.
914  * @c: The controller.
915  */
916 void ssam_controller_put(struct ssam_controller *c)
917 {
918 	if (c)
919 		kref_put(&c->kref, __ssam_controller_release);
920 }
921 EXPORT_SYMBOL_GPL(ssam_controller_put);
922 
923 /**
924  * ssam_controller_statelock() - Lock the controller against state transitions.
925  * @c: The controller to lock.
926  *
927  * Lock the controller against state transitions. Holding this lock guarantees
928  * that the controller will not transition between states, i.e. if the
929  * controller is in state "started", when this lock has been acquired, it will
930  * remain in this state at least until the lock has been released.
931  *
932  * Multiple clients may concurrently hold this lock. In other words: The
933  * ``statelock`` functions represent the read-lock part of a r/w-semaphore.
934  * Actions causing state transitions of the controller must be executed while
935  * holding the write-part of this r/w-semaphore (see ssam_controller_lock()
936  * and ssam_controller_unlock() for that).
937  *
938  * See ssam_controller_stateunlock() for the corresponding unlock function.
939  */
940 void ssam_controller_statelock(struct ssam_controller *c)
941 {
942 	down_read(&c->lock);
943 }
944 EXPORT_SYMBOL_GPL(ssam_controller_statelock);
945 
946 /**
947  * ssam_controller_stateunlock() - Unlock controller state transitions.
948  * @c: The controller to unlock.
949  *
950  * See ssam_controller_statelock() for the corresponding lock function.
951  */
952 void ssam_controller_stateunlock(struct ssam_controller *c)
953 {
954 	up_read(&c->lock);
955 }
956 EXPORT_SYMBOL_GPL(ssam_controller_stateunlock);
957 
958 /**
959  * ssam_controller_lock() - Acquire the main controller lock.
960  * @c: The controller to lock.
961  *
962  * This lock must be held for any state transitions, including transition to
963  * suspend/resumed states and during shutdown. See ssam_controller_statelock()
964  * for more details on controller locking.
965  *
966  * See ssam_controller_unlock() for the corresponding unlock function.
967  */
968 void ssam_controller_lock(struct ssam_controller *c)
969 {
970 	down_write(&c->lock);
971 }
972 
973 /*
974  * ssam_controller_unlock() - Release the main controller lock.
975  * @c: The controller to unlock.
976  *
977  * See ssam_controller_lock() for the corresponding lock function.
978  */
979 void ssam_controller_unlock(struct ssam_controller *c)
980 {
981 	up_write(&c->lock);
982 }
983 
984 static void ssam_handle_event(struct ssh_rtl *rtl,
985 			      const struct ssh_command *cmd,
986 			      const struct ssam_span *data)
987 {
988 	struct ssam_controller *ctrl = to_ssam_controller(rtl, rtl);
989 	struct ssam_event_item *item;
990 
991 	item = ssam_event_item_alloc(data->len, GFP_KERNEL);
992 	if (!item)
993 		return;
994 
995 	item->rqid = get_unaligned_le16(&cmd->rqid);
996 	item->event.target_category = cmd->tc;
997 	item->event.target_id = cmd->sid;
998 	item->event.command_id = cmd->cid;
999 	item->event.instance_id = cmd->iid;
1000 	memcpy(&item->event.data[0], data->ptr, data->len);
1001 
1002 	if (WARN_ON(ssam_cplt_submit_event(&ctrl->cplt, item)))
1003 		ssam_event_item_free(item);
1004 }
1005 
1006 static const struct ssh_rtl_ops ssam_rtl_ops = {
1007 	.handle_event = ssam_handle_event,
1008 };
1009 
1010 static bool ssam_notifier_is_empty(struct ssam_controller *ctrl);
1011 static void ssam_notifier_unregister_all(struct ssam_controller *ctrl);
1012 
1013 #define SSAM_SSH_DSM_REVISION	0
1014 
1015 /* d5e383e1-d892-4a76-89fc-f6aaae7ed5b5 */
1016 static const guid_t SSAM_SSH_DSM_GUID =
1017 	GUID_INIT(0xd5e383e1, 0xd892, 0x4a76,
1018 		  0x89, 0xfc, 0xf6, 0xaa, 0xae, 0x7e, 0xd5, 0xb5);
1019 
1020 enum ssh_dsm_fn {
1021 	SSH_DSM_FN_SSH_POWER_PROFILE             = 0x05,
1022 	SSH_DSM_FN_SCREEN_ON_SLEEP_IDLE_TIMEOUT  = 0x06,
1023 	SSH_DSM_FN_SCREEN_OFF_SLEEP_IDLE_TIMEOUT = 0x07,
1024 	SSH_DSM_FN_D3_CLOSES_HANDLE              = 0x08,
1025 	SSH_DSM_FN_SSH_BUFFER_SIZE               = 0x09,
1026 };
1027 
1028 static int ssam_dsm_get_functions(acpi_handle handle, u64 *funcs)
1029 {
1030 	union acpi_object *obj;
1031 	u64 mask = 0;
1032 	int i;
1033 
1034 	*funcs = 0;
1035 
1036 	/*
1037 	 * The _DSM function is only present on newer models. It is not
1038 	 * present on 5th and 6th generation devices (i.e. up to and including
1039 	 * Surface Pro 6, Surface Laptop 2, Surface Book 2).
1040 	 *
1041 	 * If the _DSM is not present, indicate that no function is supported.
1042 	 * This will result in default values being set.
1043 	 */
1044 	if (!acpi_has_method(handle, "_DSM"))
1045 		return 0;
1046 
1047 	obj = acpi_evaluate_dsm_typed(handle, &SSAM_SSH_DSM_GUID,
1048 				      SSAM_SSH_DSM_REVISION, 0, NULL,
1049 				      ACPI_TYPE_BUFFER);
1050 	if (!obj)
1051 		return -EIO;
1052 
1053 	for (i = 0; i < obj->buffer.length && i < 8; i++)
1054 		mask |= (((u64)obj->buffer.pointer[i]) << (i * 8));
1055 
1056 	if (mask & BIT(0))
1057 		*funcs = mask;
1058 
1059 	ACPI_FREE(obj);
1060 	return 0;
1061 }
1062 
1063 static int ssam_dsm_load_u32(acpi_handle handle, u64 funcs, u64 func, u32 *ret)
1064 {
1065 	union acpi_object *obj;
1066 	u64 val;
1067 
1068 	if (!(funcs & BIT_ULL(func)))
1069 		return 0; /* Not supported, leave *ret at its default value */
1070 
1071 	obj = acpi_evaluate_dsm_typed(handle, &SSAM_SSH_DSM_GUID,
1072 				      SSAM_SSH_DSM_REVISION, func, NULL,
1073 				      ACPI_TYPE_INTEGER);
1074 	if (!obj)
1075 		return -EIO;
1076 
1077 	val = obj->integer.value;
1078 	ACPI_FREE(obj);
1079 
1080 	if (val > U32_MAX)
1081 		return -ERANGE;
1082 
1083 	*ret = val;
1084 	return 0;
1085 }
1086 
1087 /**
1088  * ssam_controller_caps_load_from_acpi() - Load controller capabilities from
1089  * ACPI _DSM.
1090  * @handle: The handle of the ACPI controller/SSH device.
1091  * @caps:   Where to store the capabilities in.
1092  *
1093  * Initializes the given controller capabilities with default values, then
1094  * checks and, if the respective _DSM functions are available, loads the
1095  * actual capabilities from the _DSM.
1096  *
1097  * Return: Returns zero on success, a negative error code on failure.
1098  */
1099 static
1100 int ssam_controller_caps_load_from_acpi(acpi_handle handle,
1101 					struct ssam_controller_caps *caps)
1102 {
1103 	u32 d3_closes_handle = false;
1104 	u64 funcs;
1105 	int status;
1106 
1107 	/* Set defaults. */
1108 	caps->ssh_power_profile = U32_MAX;
1109 	caps->screen_on_sleep_idle_timeout = U32_MAX;
1110 	caps->screen_off_sleep_idle_timeout = U32_MAX;
1111 	caps->d3_closes_handle = false;
1112 	caps->ssh_buffer_size = U32_MAX;
1113 
1114 	/* Pre-load supported DSM functions. */
1115 	status = ssam_dsm_get_functions(handle, &funcs);
1116 	if (status)
1117 		return status;
1118 
1119 	/* Load actual values from ACPI, if present. */
1120 	status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_SSH_POWER_PROFILE,
1121 				   &caps->ssh_power_profile);
1122 	if (status)
1123 		return status;
1124 
1125 	status = ssam_dsm_load_u32(handle, funcs,
1126 				   SSH_DSM_FN_SCREEN_ON_SLEEP_IDLE_TIMEOUT,
1127 				   &caps->screen_on_sleep_idle_timeout);
1128 	if (status)
1129 		return status;
1130 
1131 	status = ssam_dsm_load_u32(handle, funcs,
1132 				   SSH_DSM_FN_SCREEN_OFF_SLEEP_IDLE_TIMEOUT,
1133 				   &caps->screen_off_sleep_idle_timeout);
1134 	if (status)
1135 		return status;
1136 
1137 	status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_D3_CLOSES_HANDLE,
1138 				   &d3_closes_handle);
1139 	if (status)
1140 		return status;
1141 
1142 	caps->d3_closes_handle = !!d3_closes_handle;
1143 
1144 	status = ssam_dsm_load_u32(handle, funcs, SSH_DSM_FN_SSH_BUFFER_SIZE,
1145 				   &caps->ssh_buffer_size);
1146 	if (status)
1147 		return status;
1148 
1149 	return 0;
1150 }
1151 
1152 /**
1153  * ssam_controller_init() - Initialize SSAM controller.
1154  * @ctrl:   The controller to initialize.
1155  * @serdev: The serial device representing the underlying data transport.
1156  *
1157  * Initializes the given controller. Does neither start receiver nor
1158  * transmitter threads. After this call, the controller has to be hooked up to
1159  * the serdev core separately via &struct serdev_device_ops, relaying calls to
1160  * ssam_controller_receive_buf() and ssam_controller_write_wakeup(). Once the
1161  * controller has been hooked up, transmitter and receiver threads may be
1162  * started via ssam_controller_start(). These setup steps need to be completed
1163  * before controller can be used for requests.
1164  */
1165 int ssam_controller_init(struct ssam_controller *ctrl,
1166 			 struct serdev_device *serdev)
1167 {
1168 	acpi_handle handle = ACPI_HANDLE(&serdev->dev);
1169 	int status;
1170 
1171 	init_rwsem(&ctrl->lock);
1172 	kref_init(&ctrl->kref);
1173 
1174 	status = ssam_controller_caps_load_from_acpi(handle, &ctrl->caps);
1175 	if (status)
1176 		return status;
1177 
1178 	dev_dbg(&serdev->dev,
1179 		"device capabilities:\n"
1180 		"  ssh_power_profile:             %u\n"
1181 		"  ssh_buffer_size:               %u\n"
1182 		"  screen_on_sleep_idle_timeout:  %u\n"
1183 		"  screen_off_sleep_idle_timeout: %u\n"
1184 		"  d3_closes_handle:              %u\n",
1185 		ctrl->caps.ssh_power_profile,
1186 		ctrl->caps.ssh_buffer_size,
1187 		ctrl->caps.screen_on_sleep_idle_timeout,
1188 		ctrl->caps.screen_off_sleep_idle_timeout,
1189 		ctrl->caps.d3_closes_handle);
1190 
1191 	ssh_seq_reset(&ctrl->counter.seq);
1192 	ssh_rqid_reset(&ctrl->counter.rqid);
1193 
1194 	/* Initialize event/request completion system. */
1195 	status = ssam_cplt_init(&ctrl->cplt, &serdev->dev);
1196 	if (status)
1197 		return status;
1198 
1199 	/* Initialize request and packet transport layers. */
1200 	status = ssh_rtl_init(&ctrl->rtl, serdev, &ssam_rtl_ops);
1201 	if (status) {
1202 		ssam_cplt_destroy(&ctrl->cplt);
1203 		return status;
1204 	}
1205 
1206 	/*
1207 	 * Set state via write_once even though we expect to be in an
1208 	 * exclusive context, due to smoke-testing in
1209 	 * ssam_request_sync_submit().
1210 	 */
1211 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_INITIALIZED);
1212 	return 0;
1213 }
1214 
1215 /**
1216  * ssam_controller_start() - Start the receiver and transmitter threads of the
1217  * controller.
1218  * @ctrl: The controller.
1219  *
1220  * Note: When this function is called, the controller should be properly
1221  * hooked up to the serdev core via &struct serdev_device_ops. Please refer
1222  * to ssam_controller_init() for more details on controller initialization.
1223  *
1224  * This function must be called with the main controller lock held (i.e. by
1225  * calling ssam_controller_lock()).
1226  */
1227 int ssam_controller_start(struct ssam_controller *ctrl)
1228 {
1229 	int status;
1230 
1231 	lockdep_assert_held_write(&ctrl->lock);
1232 
1233 	if (ctrl->state != SSAM_CONTROLLER_INITIALIZED)
1234 		return -EINVAL;
1235 
1236 	status = ssh_rtl_start(&ctrl->rtl);
1237 	if (status)
1238 		return status;
1239 
1240 	/*
1241 	 * Set state via write_once even though we expect to be locked/in an
1242 	 * exclusive context, due to smoke-testing in
1243 	 * ssam_request_sync_submit().
1244 	 */
1245 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STARTED);
1246 	return 0;
1247 }
1248 
1249 /*
1250  * SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT - Timeout for flushing requests during
1251  * shutdown.
1252  *
1253  * Chosen to be larger than one full request timeout, including packets timing
1254  * out. This value should give ample time to complete any outstanding requests
1255  * during normal operation and account for the odd package timeout.
1256  */
1257 #define SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT	msecs_to_jiffies(5000)
1258 
1259 /**
1260  * ssam_controller_shutdown() - Shut down the controller.
1261  * @ctrl: The controller.
1262  *
1263  * Shuts down the controller by flushing all pending requests and stopping the
1264  * transmitter and receiver threads. All requests submitted after this call
1265  * will fail with %-ESHUTDOWN. While it is discouraged to do so, this function
1266  * is safe to use in parallel with ongoing request submission.
1267  *
1268  * In the course of this shutdown procedure, all currently registered
1269  * notifiers will be unregistered. It is, however, strongly recommended to not
1270  * rely on this behavior, and instead the party registering the notifier
1271  * should unregister it before the controller gets shut down, e.g. via the
1272  * SSAM bus which guarantees client devices to be removed before a shutdown.
1273  *
1274  * Note that events may still be pending after this call, but, due to the
1275  * notifiers being unregistered, these events will be dropped when the
1276  * controller is subsequently destroyed via ssam_controller_destroy().
1277  *
1278  * This function must be called with the main controller lock held (i.e. by
1279  * calling ssam_controller_lock()).
1280  */
1281 void ssam_controller_shutdown(struct ssam_controller *ctrl)
1282 {
1283 	enum ssam_controller_state s = ctrl->state;
1284 	int status;
1285 
1286 	lockdep_assert_held_write(&ctrl->lock);
1287 
1288 	if (s == SSAM_CONTROLLER_UNINITIALIZED || s == SSAM_CONTROLLER_STOPPED)
1289 		return;
1290 
1291 	/*
1292 	 * Try to flush pending events and requests while everything still
1293 	 * works. Note: There may still be packets and/or requests in the
1294 	 * system after this call (e.g. via control packets submitted by the
1295 	 * packet transport layer or flush timeout / failure, ...). Those will
1296 	 * be handled with the ssh_rtl_shutdown() call below.
1297 	 */
1298 	status = ssh_rtl_flush(&ctrl->rtl, SSAM_CTRL_SHUTDOWN_FLUSH_TIMEOUT);
1299 	if (status) {
1300 		ssam_err(ctrl, "failed to flush request transport layer: %d\n",
1301 			 status);
1302 	}
1303 
1304 	/* Try to flush all currently completing requests and events. */
1305 	ssam_cplt_flush(&ctrl->cplt);
1306 
1307 	/*
1308 	 * We expect all notifiers to have been removed by the respective client
1309 	 * driver that set them up at this point. If this warning occurs, some
1310 	 * client driver has not done that...
1311 	 */
1312 	WARN_ON(!ssam_notifier_is_empty(ctrl));
1313 
1314 	/*
1315 	 * Nevertheless, we should still take care of drivers that don't behave
1316 	 * well. Thus disable all enabled events, unregister all notifiers.
1317 	 */
1318 	ssam_notifier_unregister_all(ctrl);
1319 
1320 	/*
1321 	 * Cancel remaining requests. Ensure no new ones can be queued and stop
1322 	 * threads.
1323 	 */
1324 	ssh_rtl_shutdown(&ctrl->rtl);
1325 
1326 	/*
1327 	 * Set state via write_once even though we expect to be locked/in an
1328 	 * exclusive context, due to smoke-testing in
1329 	 * ssam_request_sync_submit().
1330 	 */
1331 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STOPPED);
1332 	ctrl->rtl.ptl.serdev = NULL;
1333 }
1334 
1335 /**
1336  * ssam_controller_destroy() - Destroy the controller and free its resources.
1337  * @ctrl: The controller.
1338  *
1339  * Ensures that all resources associated with the controller get freed. This
1340  * function should only be called after the controller has been stopped via
1341  * ssam_controller_shutdown(). In general, this function should not be called
1342  * directly. The only valid place to call this function directly is during
1343  * initialization, before the controller has been fully initialized and passed
1344  * to other processes. This function is called automatically when the
1345  * reference count of the controller reaches zero.
1346  *
1347  * This function must be called with the main controller lock held (i.e. by
1348  * calling ssam_controller_lock()).
1349  */
1350 void ssam_controller_destroy(struct ssam_controller *ctrl)
1351 {
1352 	lockdep_assert_held_write(&ctrl->lock);
1353 
1354 	if (ctrl->state == SSAM_CONTROLLER_UNINITIALIZED)
1355 		return;
1356 
1357 	WARN_ON(ctrl->state != SSAM_CONTROLLER_STOPPED);
1358 
1359 	/*
1360 	 * Note: New events could still have been received after the previous
1361 	 * flush in ssam_controller_shutdown, before the request transport layer
1362 	 * has been shut down. At this point, after the shutdown, we can be sure
1363 	 * that no new events will be queued. The call to ssam_cplt_destroy will
1364 	 * ensure that those remaining are being completed and freed.
1365 	 */
1366 
1367 	/* Actually free resources. */
1368 	ssam_cplt_destroy(&ctrl->cplt);
1369 	ssh_rtl_destroy(&ctrl->rtl);
1370 
1371 	/*
1372 	 * Set state via write_once even though we expect to be locked/in an
1373 	 * exclusive context, due to smoke-testing in
1374 	 * ssam_request_sync_submit().
1375 	 */
1376 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_UNINITIALIZED);
1377 }
1378 
1379 /**
1380  * ssam_controller_suspend() - Suspend the controller.
1381  * @ctrl: The controller to suspend.
1382  *
1383  * Marks the controller as suspended. Note that display-off and D0-exit
1384  * notifications have to be sent manually before transitioning the controller
1385  * into the suspended state via this function.
1386  *
1387  * See ssam_controller_resume() for the corresponding resume function.
1388  *
1389  * Return: Returns %-EINVAL if the controller is currently not in the
1390  * "started" state.
1391  */
1392 int ssam_controller_suspend(struct ssam_controller *ctrl)
1393 {
1394 	ssam_controller_lock(ctrl);
1395 
1396 	if (ctrl->state != SSAM_CONTROLLER_STARTED) {
1397 		ssam_controller_unlock(ctrl);
1398 		return -EINVAL;
1399 	}
1400 
1401 	ssam_dbg(ctrl, "pm: suspending controller\n");
1402 
1403 	/*
1404 	 * Set state via write_once even though we're locked, due to
1405 	 * smoke-testing in ssam_request_sync_submit().
1406 	 */
1407 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_SUSPENDED);
1408 
1409 	ssam_controller_unlock(ctrl);
1410 	return 0;
1411 }
1412 
1413 /**
1414  * ssam_controller_resume() - Resume the controller from suspend.
1415  * @ctrl: The controller to resume.
1416  *
1417  * Resume the controller from the suspended state it was put into via
1418  * ssam_controller_suspend(). This function does not issue display-on and
1419  * D0-entry notifications. If required, those have to be sent manually after
1420  * this call.
1421  *
1422  * Return: Returns %-EINVAL if the controller is currently not suspended.
1423  */
1424 int ssam_controller_resume(struct ssam_controller *ctrl)
1425 {
1426 	ssam_controller_lock(ctrl);
1427 
1428 	if (ctrl->state != SSAM_CONTROLLER_SUSPENDED) {
1429 		ssam_controller_unlock(ctrl);
1430 		return -EINVAL;
1431 	}
1432 
1433 	ssam_dbg(ctrl, "pm: resuming controller\n");
1434 
1435 	/*
1436 	 * Set state via write_once even though we're locked, due to
1437 	 * smoke-testing in ssam_request_sync_submit().
1438 	 */
1439 	WRITE_ONCE(ctrl->state, SSAM_CONTROLLER_STARTED);
1440 
1441 	ssam_controller_unlock(ctrl);
1442 	return 0;
1443 }
1444 
1445 
1446 /* -- Top-level request interface ------------------------------------------- */
1447 
1448 /**
1449  * ssam_request_write_data() - Construct and write SAM request message to
1450  * buffer.
1451  * @buf:  The buffer to write the data to.
1452  * @ctrl: The controller via which the request will be sent.
1453  * @spec: The request data and specification.
1454  *
1455  * Constructs a SAM/SSH request message and writes it to the provided buffer.
1456  * The request and transport counters, specifically RQID and SEQ, will be set
1457  * in this call. These counters are obtained from the controller. It is thus
1458  * only valid to send the resulting message via the controller specified here.
1459  *
1460  * For calculation of the required buffer size, refer to the
1461  * SSH_COMMAND_MESSAGE_LENGTH() macro.
1462  *
1463  * Return: Returns the number of bytes used in the buffer on success. Returns
1464  * %-EINVAL if the payload length provided in the request specification is too
1465  * large (larger than %SSH_COMMAND_MAX_PAYLOAD_SIZE) or if the provided buffer
1466  * is too small.
1467  */
1468 ssize_t ssam_request_write_data(struct ssam_span *buf,
1469 				struct ssam_controller *ctrl,
1470 				const struct ssam_request *spec)
1471 {
1472 	struct msgbuf msgb;
1473 	u16 rqid;
1474 	u8 seq;
1475 
1476 	if (spec->length > SSH_COMMAND_MAX_PAYLOAD_SIZE)
1477 		return -EINVAL;
1478 
1479 	if (SSH_COMMAND_MESSAGE_LENGTH(spec->length) > buf->len)
1480 		return -EINVAL;
1481 
1482 	msgb_init(&msgb, buf->ptr, buf->len);
1483 	seq = ssh_seq_next(&ctrl->counter.seq);
1484 	rqid = ssh_rqid_next(&ctrl->counter.rqid);
1485 	msgb_push_cmd(&msgb, seq, rqid, spec);
1486 
1487 	return msgb_bytes_used(&msgb);
1488 }
1489 EXPORT_SYMBOL_GPL(ssam_request_write_data);
1490 
1491 static void ssam_request_sync_complete(struct ssh_request *rqst,
1492 				       const struct ssh_command *cmd,
1493 				       const struct ssam_span *data, int status)
1494 {
1495 	struct ssh_rtl *rtl = ssh_request_rtl(rqst);
1496 	struct ssam_request_sync *r;
1497 
1498 	r = container_of(rqst, struct ssam_request_sync, base);
1499 	r->status = status;
1500 
1501 	if (r->resp)
1502 		r->resp->length = 0;
1503 
1504 	if (status) {
1505 		rtl_dbg_cond(rtl, "rsp: request failed: %d\n", status);
1506 		return;
1507 	}
1508 
1509 	if (!data)	/* Handle requests without a response. */
1510 		return;
1511 
1512 	if (!r->resp || !r->resp->pointer) {
1513 		if (data->len)
1514 			rtl_warn(rtl, "rsp: no response buffer provided, dropping data\n");
1515 		return;
1516 	}
1517 
1518 	if (data->len > r->resp->capacity) {
1519 		rtl_err(rtl,
1520 			"rsp: response buffer too small, capacity: %zu bytes, got: %zu bytes\n",
1521 			r->resp->capacity, data->len);
1522 		r->status = -ENOSPC;
1523 		return;
1524 	}
1525 
1526 	r->resp->length = data->len;
1527 	memcpy(r->resp->pointer, data->ptr, data->len);
1528 }
1529 
1530 static void ssam_request_sync_release(struct ssh_request *rqst)
1531 {
1532 	complete_all(&container_of(rqst, struct ssam_request_sync, base)->comp);
1533 }
1534 
1535 static const struct ssh_request_ops ssam_request_sync_ops = {
1536 	.release = ssam_request_sync_release,
1537 	.complete = ssam_request_sync_complete,
1538 };
1539 
1540 /**
1541  * ssam_request_sync_alloc() - Allocate a synchronous request.
1542  * @payload_len: The length of the request payload.
1543  * @flags:       Flags used for allocation.
1544  * @rqst:        Where to store the pointer to the allocated request.
1545  * @buffer:      Where to store the buffer descriptor for the message buffer of
1546  *               the request.
1547  *
1548  * Allocates a synchronous request with corresponding message buffer. The
1549  * request still needs to be initialized ssam_request_sync_init() before
1550  * it can be submitted, and the message buffer data must still be set to the
1551  * returned buffer via ssam_request_sync_set_data() after it has been filled,
1552  * if need be with adjusted message length.
1553  *
1554  * After use, the request and its corresponding message buffer should be freed
1555  * via ssam_request_sync_free(). The buffer must not be freed separately.
1556  *
1557  * Return: Returns zero on success, %-ENOMEM if the request could not be
1558  * allocated.
1559  */
1560 int ssam_request_sync_alloc(size_t payload_len, gfp_t flags,
1561 			    struct ssam_request_sync **rqst,
1562 			    struct ssam_span *buffer)
1563 {
1564 	size_t msglen = SSH_COMMAND_MESSAGE_LENGTH(payload_len);
1565 
1566 	*rqst = kzalloc(sizeof(**rqst) + msglen, flags);
1567 	if (!*rqst)
1568 		return -ENOMEM;
1569 
1570 	buffer->ptr = (u8 *)(*rqst + 1);
1571 	buffer->len = msglen;
1572 
1573 	return 0;
1574 }
1575 EXPORT_SYMBOL_GPL(ssam_request_sync_alloc);
1576 
1577 /**
1578  * ssam_request_sync_free() - Free a synchronous request.
1579  * @rqst: The request to be freed.
1580  *
1581  * Free a synchronous request and its corresponding buffer allocated with
1582  * ssam_request_sync_alloc(). Do not use for requests allocated on the stack
1583  * or via any other function.
1584  *
1585  * Warning: The caller must ensure that the request is not in use any more.
1586  * I.e. the caller must ensure that it has the only reference to the request
1587  * and the request is not currently pending. This means that the caller has
1588  * either never submitted the request, request submission has failed, or the
1589  * caller has waited until the submitted request has been completed via
1590  * ssam_request_sync_wait().
1591  */
1592 void ssam_request_sync_free(struct ssam_request_sync *rqst)
1593 {
1594 	kfree(rqst);
1595 }
1596 EXPORT_SYMBOL_GPL(ssam_request_sync_free);
1597 
1598 /**
1599  * ssam_request_sync_init() - Initialize a synchronous request struct.
1600  * @rqst:  The request to initialize.
1601  * @flags: The request flags.
1602  *
1603  * Initializes the given request struct. Does not initialize the request
1604  * message data. This has to be done explicitly after this call via
1605  * ssam_request_sync_set_data() and the actual message data has to be written
1606  * via ssam_request_write_data().
1607  *
1608  * Return: Returns zero on success or %-EINVAL if the given flags are invalid.
1609  */
1610 int ssam_request_sync_init(struct ssam_request_sync *rqst,
1611 			   enum ssam_request_flags flags)
1612 {
1613 	int status;
1614 
1615 	status = ssh_request_init(&rqst->base, flags, &ssam_request_sync_ops);
1616 	if (status)
1617 		return status;
1618 
1619 	init_completion(&rqst->comp);
1620 	rqst->resp = NULL;
1621 	rqst->status = 0;
1622 
1623 	return 0;
1624 }
1625 EXPORT_SYMBOL_GPL(ssam_request_sync_init);
1626 
1627 /**
1628  * ssam_request_sync_submit() - Submit a synchronous request.
1629  * @ctrl: The controller with which to submit the request.
1630  * @rqst: The request to submit.
1631  *
1632  * Submit a synchronous request. The request has to be initialized and
1633  * properly set up, including response buffer (may be %NULL if no response is
1634  * expected) and command message data. This function does not wait for the
1635  * request to be completed.
1636  *
1637  * If this function succeeds, ssam_request_sync_wait() must be used to ensure
1638  * that the request has been completed before the response data can be
1639  * accessed and/or the request can be freed. On failure, the request may
1640  * immediately be freed.
1641  *
1642  * This function may only be used if the controller is active, i.e. has been
1643  * initialized and not suspended.
1644  */
1645 int ssam_request_sync_submit(struct ssam_controller *ctrl,
1646 			     struct ssam_request_sync *rqst)
1647 {
1648 	int status;
1649 
1650 	/*
1651 	 * This is only a superficial check. In general, the caller needs to
1652 	 * ensure that the controller is initialized and is not (and does not
1653 	 * get) suspended during use, i.e. until the request has been completed
1654 	 * (if _absolutely_ necessary, by use of ssam_controller_statelock/
1655 	 * ssam_controller_stateunlock, but something like ssam_client_link
1656 	 * should be preferred as this needs to last until the request has been
1657 	 * completed).
1658 	 *
1659 	 * Note that it is actually safe to use this function while the
1660 	 * controller is in the process of being shut down (as ssh_rtl_submit
1661 	 * is safe with regards to this), but it is generally discouraged to do
1662 	 * so.
1663 	 */
1664 	if (WARN_ON(READ_ONCE(ctrl->state) != SSAM_CONTROLLER_STARTED)) {
1665 		ssh_request_put(&rqst->base);
1666 		return -ENODEV;
1667 	}
1668 
1669 	status = ssh_rtl_submit(&ctrl->rtl, &rqst->base);
1670 	ssh_request_put(&rqst->base);
1671 
1672 	return status;
1673 }
1674 EXPORT_SYMBOL_GPL(ssam_request_sync_submit);
1675 
1676 /**
1677  * ssam_request_do_sync() - Execute a synchronous request.
1678  * @ctrl: The controller via which the request will be submitted.
1679  * @spec: The request specification and payload.
1680  * @rsp:  The response buffer.
1681  *
1682  * Allocates a synchronous request with its message data buffer on the heap
1683  * via ssam_request_sync_alloc(), fully initializes it via the provided
1684  * request specification, submits it, and finally waits for its completion
1685  * before freeing it and returning its status.
1686  *
1687  * Return: Returns the status of the request or any failure during setup.
1688  */
1689 int ssam_request_do_sync(struct ssam_controller *ctrl,
1690 			 const struct ssam_request *spec,
1691 			 struct ssam_response *rsp)
1692 {
1693 	struct ssam_request_sync *rqst;
1694 	struct ssam_span buf;
1695 	ssize_t len;
1696 	int status;
1697 
1698 	status = ssam_request_sync_alloc(spec->length, GFP_KERNEL, &rqst, &buf);
1699 	if (status)
1700 		return status;
1701 
1702 	status = ssam_request_sync_init(rqst, spec->flags);
1703 	if (status) {
1704 		ssam_request_sync_free(rqst);
1705 		return status;
1706 	}
1707 
1708 	ssam_request_sync_set_resp(rqst, rsp);
1709 
1710 	len = ssam_request_write_data(&buf, ctrl, spec);
1711 	if (len < 0) {
1712 		ssam_request_sync_free(rqst);
1713 		return len;
1714 	}
1715 
1716 	ssam_request_sync_set_data(rqst, buf.ptr, len);
1717 
1718 	status = ssam_request_sync_submit(ctrl, rqst);
1719 	if (!status)
1720 		status = ssam_request_sync_wait(rqst);
1721 
1722 	ssam_request_sync_free(rqst);
1723 	return status;
1724 }
1725 EXPORT_SYMBOL_GPL(ssam_request_do_sync);
1726 
1727 /**
1728  * ssam_request_do_sync_with_buffer() - Execute a synchronous request with the
1729  * provided buffer as back-end for the message buffer.
1730  * @ctrl: The controller via which the request will be submitted.
1731  * @spec: The request specification and payload.
1732  * @rsp:  The response buffer.
1733  * @buf:  The buffer for the request message data.
1734  *
1735  * Allocates a synchronous request struct on the stack, fully initializes it
1736  * using the provided buffer as message data buffer, submits it, and then
1737  * waits for its completion before returning its status. The
1738  * SSH_COMMAND_MESSAGE_LENGTH() macro can be used to compute the required
1739  * message buffer size.
1740  *
1741  * This function does essentially the same as ssam_request_do_sync(), but
1742  * instead of dynamically allocating the request and message data buffer, it
1743  * uses the provided message data buffer and stores the (small) request struct
1744  * on the heap.
1745  *
1746  * Return: Returns the status of the request or any failure during setup.
1747  */
1748 int ssam_request_do_sync_with_buffer(struct ssam_controller *ctrl,
1749 				     const struct ssam_request *spec,
1750 				     struct ssam_response *rsp,
1751 				     struct ssam_span *buf)
1752 {
1753 	struct ssam_request_sync rqst;
1754 	ssize_t len;
1755 	int status;
1756 
1757 	status = ssam_request_sync_init(&rqst, spec->flags);
1758 	if (status)
1759 		return status;
1760 
1761 	ssam_request_sync_set_resp(&rqst, rsp);
1762 
1763 	len = ssam_request_write_data(buf, ctrl, spec);
1764 	if (len < 0)
1765 		return len;
1766 
1767 	ssam_request_sync_set_data(&rqst, buf->ptr, len);
1768 
1769 	status = ssam_request_sync_submit(ctrl, &rqst);
1770 	if (!status)
1771 		status = ssam_request_sync_wait(&rqst);
1772 
1773 	return status;
1774 }
1775 EXPORT_SYMBOL_GPL(ssam_request_do_sync_with_buffer);
1776 
1777 
1778 /* -- Internal SAM requests. ------------------------------------------------ */
1779 
1780 SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_get_firmware_version, __le32, {
1781 	.target_category = SSAM_SSH_TC_SAM,
1782 	.target_id       = SSAM_SSH_TID_SAM,
1783 	.command_id      = 0x13,
1784 	.instance_id     = 0x00,
1785 });
1786 
1787 SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_off, u8, {
1788 	.target_category = SSAM_SSH_TC_SAM,
1789 	.target_id       = SSAM_SSH_TID_SAM,
1790 	.command_id      = 0x15,
1791 	.instance_id     = 0x00,
1792 });
1793 
1794 SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_display_on, u8, {
1795 	.target_category = SSAM_SSH_TC_SAM,
1796 	.target_id       = SSAM_SSH_TID_SAM,
1797 	.command_id      = 0x16,
1798 	.instance_id     = 0x00,
1799 });
1800 
1801 SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_exit, u8, {
1802 	.target_category = SSAM_SSH_TC_SAM,
1803 	.target_id       = SSAM_SSH_TID_SAM,
1804 	.command_id      = 0x33,
1805 	.instance_id     = 0x00,
1806 });
1807 
1808 SSAM_DEFINE_SYNC_REQUEST_R(ssam_ssh_notif_d0_entry, u8, {
1809 	.target_category = SSAM_SSH_TC_SAM,
1810 	.target_id       = SSAM_SSH_TID_SAM,
1811 	.command_id      = 0x34,
1812 	.instance_id     = 0x00,
1813 });
1814 
1815 /**
1816  * struct ssh_notification_params - Command payload to enable/disable SSH
1817  * notifications.
1818  * @target_category: The target category for which notifications should be
1819  *                   enabled/disabled.
1820  * @flags:           Flags determining how notifications are being sent.
1821  * @request_id:      The request ID that is used to send these notifications.
1822  * @instance_id:     The specific instance in the given target category for
1823  *                   which notifications should be enabled.
1824  */
1825 struct ssh_notification_params {
1826 	u8 target_category;
1827 	u8 flags;
1828 	__le16 request_id;
1829 	u8 instance_id;
1830 } __packed;
1831 
1832 static_assert(sizeof(struct ssh_notification_params) == 5);
1833 
1834 static int __ssam_ssh_event_request(struct ssam_controller *ctrl,
1835 				    struct ssam_event_registry reg, u8 cid,
1836 				    struct ssam_event_id id, u8 flags)
1837 {
1838 	struct ssh_notification_params params;
1839 	struct ssam_request rqst;
1840 	struct ssam_response result;
1841 	int status;
1842 
1843 	u16 rqid = ssh_tc_to_rqid(id.target_category);
1844 	u8 buf = 0;
1845 
1846 	/* Only allow RQIDs that lie within the event spectrum. */
1847 	if (!ssh_rqid_is_event(rqid))
1848 		return -EINVAL;
1849 
1850 	params.target_category = id.target_category;
1851 	params.instance_id = id.instance;
1852 	params.flags = flags;
1853 	put_unaligned_le16(rqid, &params.request_id);
1854 
1855 	rqst.target_category = reg.target_category;
1856 	rqst.target_id = reg.target_id;
1857 	rqst.command_id = cid;
1858 	rqst.instance_id = 0x00;
1859 	rqst.flags = SSAM_REQUEST_HAS_RESPONSE;
1860 	rqst.length = sizeof(params);
1861 	rqst.payload = (u8 *)&params;
1862 
1863 	result.capacity = sizeof(buf);
1864 	result.length = 0;
1865 	result.pointer = &buf;
1866 
1867 	status = ssam_retry(ssam_request_do_sync_onstack, ctrl, &rqst, &result,
1868 			    sizeof(params));
1869 
1870 	return status < 0 ? status : buf;
1871 }
1872 
1873 /**
1874  * ssam_ssh_event_enable() - Enable SSH event.
1875  * @ctrl:  The controller for which to enable the event.
1876  * @reg:   The event registry describing what request to use for enabling and
1877  *         disabling the event.
1878  * @id:    The event identifier.
1879  * @flags: The event flags.
1880  *
1881  * Enables the specified event on the EC. This function does not manage
1882  * reference counting of enabled events and is basically only a wrapper for
1883  * the raw EC request. If the specified event is already enabled, the EC will
1884  * ignore this request.
1885  *
1886  * Return: Returns the status of the executed SAM request (zero on success and
1887  * negative on direct failure) or %-EPROTO if the request response indicates a
1888  * failure.
1889  */
1890 static int ssam_ssh_event_enable(struct ssam_controller *ctrl,
1891 				 struct ssam_event_registry reg,
1892 				 struct ssam_event_id id, u8 flags)
1893 {
1894 	int status;
1895 
1896 	status = __ssam_ssh_event_request(ctrl, reg, reg.cid_enable, id, flags);
1897 
1898 	if (status < 0 && status != -EINVAL) {
1899 		ssam_err(ctrl,
1900 			 "failed to enable event source (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1901 			 id.target_category, id.instance, reg.target_category);
1902 	}
1903 
1904 	if (status > 0) {
1905 		ssam_err(ctrl,
1906 			 "unexpected result while enabling event source: %#04x (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1907 			 status, id.target_category, id.instance, reg.target_category);
1908 		return -EPROTO;
1909 	}
1910 
1911 	return status;
1912 }
1913 
1914 /**
1915  * ssam_ssh_event_disable() - Disable SSH event.
1916  * @ctrl:  The controller for which to disable the event.
1917  * @reg:   The event registry describing what request to use for enabling and
1918  *         disabling the event (must be same as used when enabling the event).
1919  * @id:    The event identifier.
1920  * @flags: The event flags (likely ignored for disabling of events).
1921  *
1922  * Disables the specified event on the EC. This function does not manage
1923  * reference counting of enabled events and is basically only a wrapper for
1924  * the raw EC request. If the specified event is already disabled, the EC will
1925  * ignore this request.
1926  *
1927  * Return: Returns the status of the executed SAM request (zero on success and
1928  * negative on direct failure) or %-EPROTO if the request response indicates a
1929  * failure.
1930  */
1931 static int ssam_ssh_event_disable(struct ssam_controller *ctrl,
1932 				  struct ssam_event_registry reg,
1933 				  struct ssam_event_id id, u8 flags)
1934 {
1935 	int status;
1936 
1937 	status = __ssam_ssh_event_request(ctrl, reg, reg.cid_disable, id, flags);
1938 
1939 	if (status < 0 && status != -EINVAL) {
1940 		ssam_err(ctrl,
1941 			 "failed to disable event source (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1942 			 id.target_category, id.instance, reg.target_category);
1943 	}
1944 
1945 	if (status > 0) {
1946 		ssam_err(ctrl,
1947 			 "unexpected result while disabling event source: %#04x (tc: %#04x, iid: %#04x, reg: %#04x)\n",
1948 			 status, id.target_category, id.instance, reg.target_category);
1949 		return -EPROTO;
1950 	}
1951 
1952 	return status;
1953 }
1954 
1955 
1956 /* -- Wrappers for internal SAM requests. ----------------------------------- */
1957 
1958 /**
1959  * ssam_get_firmware_version() - Get the SAM/EC firmware version.
1960  * @ctrl:    The controller.
1961  * @version: Where to store the version number.
1962  *
1963  * Return: Returns zero on success or the status of the executed SAM request
1964  * if that request failed.
1965  */
1966 int ssam_get_firmware_version(struct ssam_controller *ctrl, u32 *version)
1967 {
1968 	__le32 __version;
1969 	int status;
1970 
1971 	status = ssam_retry(ssam_ssh_get_firmware_version, ctrl, &__version);
1972 	if (status)
1973 		return status;
1974 
1975 	*version = le32_to_cpu(__version);
1976 	return 0;
1977 }
1978 
1979 /**
1980  * ssam_ctrl_notif_display_off() - Notify EC that the display has been turned
1981  * off.
1982  * @ctrl: The controller.
1983  *
1984  * Notify the EC that the display has been turned off and the driver may enter
1985  * a lower-power state. This will prevent events from being sent directly.
1986  * Rather, the EC signals an event by pulling the wakeup GPIO high for as long
1987  * as there are pending events. The events then need to be manually released,
1988  * one by one, via the GPIO callback request. All pending events accumulated
1989  * during this state can also be released by issuing the display-on
1990  * notification, e.g. via ssam_ctrl_notif_display_on(), which will also reset
1991  * the GPIO.
1992  *
1993  * On some devices, specifically ones with an integrated keyboard, the keyboard
1994  * backlight will be turned off by this call.
1995  *
1996  * This function will only send the display-off notification command if
1997  * display notifications are supported by the EC. Currently all known devices
1998  * support these notifications.
1999  *
2000  * Use ssam_ctrl_notif_display_on() to reverse the effects of this function.
2001  *
2002  * Return: Returns zero on success or if no request has been executed, the
2003  * status of the executed SAM request if that request failed, or %-EPROTO if
2004  * an unexpected response has been received.
2005  */
2006 int ssam_ctrl_notif_display_off(struct ssam_controller *ctrl)
2007 {
2008 	int status;
2009 	u8 response;
2010 
2011 	ssam_dbg(ctrl, "pm: notifying display off\n");
2012 
2013 	status = ssam_retry(ssam_ssh_notif_display_off, ctrl, &response);
2014 	if (status)
2015 		return status;
2016 
2017 	if (response != 0) {
2018 		ssam_err(ctrl, "unexpected response from display-off notification: %#04x\n",
2019 			 response);
2020 		return -EPROTO;
2021 	}
2022 
2023 	return 0;
2024 }
2025 
2026 /**
2027  * ssam_ctrl_notif_display_on() - Notify EC that the display has been turned on.
2028  * @ctrl: The controller.
2029  *
2030  * Notify the EC that the display has been turned back on and the driver has
2031  * exited its lower-power state. This notification is the counterpart to the
2032  * display-off notification sent via ssam_ctrl_notif_display_off() and will
2033  * reverse its effects, including resetting events to their default behavior.
2034  *
2035  * This function will only send the display-on notification command if display
2036  * notifications are supported by the EC. Currently all known devices support
2037  * these notifications.
2038  *
2039  * See ssam_ctrl_notif_display_off() for more details.
2040  *
2041  * Return: Returns zero on success or if no request has been executed, the
2042  * status of the executed SAM request if that request failed, or %-EPROTO if
2043  * an unexpected response has been received.
2044  */
2045 int ssam_ctrl_notif_display_on(struct ssam_controller *ctrl)
2046 {
2047 	int status;
2048 	u8 response;
2049 
2050 	ssam_dbg(ctrl, "pm: notifying display on\n");
2051 
2052 	status = ssam_retry(ssam_ssh_notif_display_on, ctrl, &response);
2053 	if (status)
2054 		return status;
2055 
2056 	if (response != 0) {
2057 		ssam_err(ctrl, "unexpected response from display-on notification: %#04x\n",
2058 			 response);
2059 		return -EPROTO;
2060 	}
2061 
2062 	return 0;
2063 }
2064 
2065 /**
2066  * ssam_ctrl_notif_d0_exit() - Notify EC that the driver/device exits the D0
2067  * power state.
2068  * @ctrl: The controller
2069  *
2070  * Notifies the EC that the driver prepares to exit the D0 power state in
2071  * favor of a lower-power state. Exact effects of this function related to the
2072  * EC are currently unknown.
2073  *
2074  * This function will only send the D0-exit notification command if D0-state
2075  * notifications are supported by the EC. Only newer Surface generations
2076  * support these notifications.
2077  *
2078  * Use ssam_ctrl_notif_d0_entry() to reverse the effects of this function.
2079  *
2080  * Return: Returns zero on success or if no request has been executed, the
2081  * status of the executed SAM request if that request failed, or %-EPROTO if
2082  * an unexpected response has been received.
2083  */
2084 int ssam_ctrl_notif_d0_exit(struct ssam_controller *ctrl)
2085 {
2086 	int status;
2087 	u8 response;
2088 
2089 	if (!ctrl->caps.d3_closes_handle)
2090 		return 0;
2091 
2092 	ssam_dbg(ctrl, "pm: notifying D0 exit\n");
2093 
2094 	status = ssam_retry(ssam_ssh_notif_d0_exit, ctrl, &response);
2095 	if (status)
2096 		return status;
2097 
2098 	if (response != 0) {
2099 		ssam_err(ctrl, "unexpected response from D0-exit notification: %#04x\n",
2100 			 response);
2101 		return -EPROTO;
2102 	}
2103 
2104 	return 0;
2105 }
2106 
2107 /**
2108  * ssam_ctrl_notif_d0_entry() - Notify EC that the driver/device enters the D0
2109  * power state.
2110  * @ctrl: The controller
2111  *
2112  * Notifies the EC that the driver has exited a lower-power state and entered
2113  * the D0 power state. Exact effects of this function related to the EC are
2114  * currently unknown.
2115  *
2116  * This function will only send the D0-entry notification command if D0-state
2117  * notifications are supported by the EC. Only newer Surface generations
2118  * support these notifications.
2119  *
2120  * See ssam_ctrl_notif_d0_exit() for more details.
2121  *
2122  * Return: Returns zero on success or if no request has been executed, the
2123  * status of the executed SAM request if that request failed, or %-EPROTO if
2124  * an unexpected response has been received.
2125  */
2126 int ssam_ctrl_notif_d0_entry(struct ssam_controller *ctrl)
2127 {
2128 	int status;
2129 	u8 response;
2130 
2131 	if (!ctrl->caps.d3_closes_handle)
2132 		return 0;
2133 
2134 	ssam_dbg(ctrl, "pm: notifying D0 entry\n");
2135 
2136 	status = ssam_retry(ssam_ssh_notif_d0_entry, ctrl, &response);
2137 	if (status)
2138 		return status;
2139 
2140 	if (response != 0) {
2141 		ssam_err(ctrl, "unexpected response from D0-entry notification: %#04x\n",
2142 			 response);
2143 		return -EPROTO;
2144 	}
2145 
2146 	return 0;
2147 }
2148 
2149 
2150 /* -- Top-level event registry interface. ----------------------------------- */
2151 
2152 /**
2153  * ssam_nf_refcount_enable() - Enable event for reference count entry if it has
2154  * not already been enabled.
2155  * @ctrl:  The controller to enable the event on.
2156  * @entry: The reference count entry for the event to be enabled.
2157  * @flags: The flags used for enabling the event on the EC.
2158  *
2159  * Enable the event associated with the given reference count entry if the
2160  * reference count equals one, i.e. the event has not previously been enabled.
2161  * If the event has already been enabled (i.e. reference count not equal to
2162  * one), check that the flags used for enabling match and warn about this if
2163  * they do not.
2164  *
2165  * This does not modify the reference count itself, which is done with
2166  * ssam_nf_refcount_inc() / ssam_nf_refcount_dec().
2167  *
2168  * Note: ``nf->lock`` must be held when calling this function.
2169  *
2170  * Return: Returns zero on success. If the event is enabled by this call,
2171  * returns the status of the event-enable EC command.
2172  */
2173 static int ssam_nf_refcount_enable(struct ssam_controller *ctrl,
2174 				   struct ssam_nf_refcount_entry *entry, u8 flags)
2175 {
2176 	const struct ssam_event_registry reg = entry->key.reg;
2177 	const struct ssam_event_id id = entry->key.id;
2178 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2179 	int status;
2180 
2181 	lockdep_assert_held(&nf->lock);
2182 
2183 	ssam_dbg(ctrl, "enabling event (reg: %#04x, tc: %#04x, iid: %#04x, rc: %d)\n",
2184 		 reg.target_category, id.target_category, id.instance, entry->refcount);
2185 
2186 	if (entry->refcount == 1) {
2187 		status = ssam_ssh_event_enable(ctrl, reg, id, flags);
2188 		if (status)
2189 			return status;
2190 
2191 		entry->flags = flags;
2192 
2193 	} else if (entry->flags != flags) {
2194 		ssam_warn(ctrl,
2195 			  "inconsistent flags when enabling event: got %#04x, expected %#04x (reg: %#04x, tc: %#04x, iid: %#04x)\n",
2196 			  flags, entry->flags, reg.target_category, id.target_category,
2197 			  id.instance);
2198 	}
2199 
2200 	return 0;
2201 }
2202 
2203 /**
2204  * ssam_nf_refcount_disable_free() - Disable event for reference count entry if
2205  * it is no longer in use and free the corresponding entry.
2206  * @ctrl:  The controller to disable the event on.
2207  * @entry: The reference count entry for the event to be disabled.
2208  * @flags: The flags used for enabling the event on the EC.
2209  * @ec:    Flag specifying if the event should actually be disabled on the EC.
2210  *
2211  * If ``ec`` equals ``true`` and the reference count equals zero (i.e. the
2212  * event is no longer requested by any client), the specified event will be
2213  * disabled on the EC via the corresponding request.
2214  *
2215  * If ``ec`` equals ``false``, no request will be sent to the EC and the event
2216  * can be considered in a detached state (i.e. no longer used but still
2217  * enabled). Disabling an event via this method may be required for
2218  * hot-removable devices, where event disable requests may time out after the
2219  * device has been physically removed.
2220  *
2221  * In both cases, if the reference count equals zero, the corresponding
2222  * reference count entry will be freed. The reference count entry must not be
2223  * used any more after a call to this function.
2224  *
2225  * Also checks if the flags used for disabling the event match the flags used
2226  * for enabling the event and warns if they do not (regardless of reference
2227  * count).
2228  *
2229  * This does not modify the reference count itself, which is done with
2230  * ssam_nf_refcount_inc() / ssam_nf_refcount_dec().
2231  *
2232  * Note: ``nf->lock`` must be held when calling this function.
2233  *
2234  * Return: Returns zero on success. If the event is disabled by this call,
2235  * returns the status of the event-enable EC command.
2236  */
2237 static int ssam_nf_refcount_disable_free(struct ssam_controller *ctrl,
2238 					 struct ssam_nf_refcount_entry *entry, u8 flags, bool ec)
2239 {
2240 	const struct ssam_event_registry reg = entry->key.reg;
2241 	const struct ssam_event_id id = entry->key.id;
2242 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2243 	int status = 0;
2244 
2245 	lockdep_assert_held(&nf->lock);
2246 
2247 	ssam_dbg(ctrl, "%s event (reg: %#04x, tc: %#04x, iid: %#04x, rc: %d)\n",
2248 		 ec ? "disabling" : "detaching", reg.target_category, id.target_category,
2249 		 id.instance, entry->refcount);
2250 
2251 	if (entry->flags != flags) {
2252 		ssam_warn(ctrl,
2253 			  "inconsistent flags when disabling event: got %#04x, expected %#04x (reg: %#04x, tc: %#04x, iid: %#04x)\n",
2254 			  flags, entry->flags, reg.target_category, id.target_category,
2255 			  id.instance);
2256 	}
2257 
2258 	if (ec && entry->refcount == 0) {
2259 		status = ssam_ssh_event_disable(ctrl, reg, id, flags);
2260 		kfree(entry);
2261 	}
2262 
2263 	return status;
2264 }
2265 
2266 /**
2267  * ssam_notifier_register() - Register an event notifier.
2268  * @ctrl: The controller to register the notifier on.
2269  * @n:    The event notifier to register.
2270  *
2271  * Register an event notifier. Increment the usage counter of the associated
2272  * SAM event if the notifier is not marked as an observer. If the event is not
2273  * marked as an observer and is currently not enabled, it will be enabled
2274  * during this call. If the notifier is marked as an observer, no attempt will
2275  * be made at enabling any event and no reference count will be modified.
2276  *
2277  * Notifiers marked as observers do not need to be associated with one specific
2278  * event, i.e. as long as no event matching is performed, only the event target
2279  * category needs to be set.
2280  *
2281  * Return: Returns zero on success, %-ENOSPC if there have already been
2282  * %INT_MAX notifiers for the event ID/type associated with the notifier block
2283  * registered, %-ENOMEM if the corresponding event entry could not be
2284  * allocated. If this is the first time that a notifier block is registered
2285  * for the specific associated event, returns the status of the event-enable
2286  * EC-command.
2287  */
2288 int ssam_notifier_register(struct ssam_controller *ctrl, struct ssam_event_notifier *n)
2289 {
2290 	u16 rqid = ssh_tc_to_rqid(n->event.id.target_category);
2291 	struct ssam_nf_refcount_entry *entry = NULL;
2292 	struct ssam_nf_head *nf_head;
2293 	struct ssam_nf *nf;
2294 	int status;
2295 
2296 	if (!ssh_rqid_is_event(rqid))
2297 		return -EINVAL;
2298 
2299 	nf = &ctrl->cplt.event.notif;
2300 	nf_head = &nf->head[ssh_rqid_to_event(rqid)];
2301 
2302 	mutex_lock(&nf->lock);
2303 
2304 	if (!(n->flags & SSAM_EVENT_NOTIFIER_OBSERVER)) {
2305 		entry = ssam_nf_refcount_inc(nf, n->event.reg, n->event.id);
2306 		if (IS_ERR(entry)) {
2307 			mutex_unlock(&nf->lock);
2308 			return PTR_ERR(entry);
2309 		}
2310 	}
2311 
2312 	status = ssam_nfblk_insert(nf_head, &n->base);
2313 	if (status) {
2314 		if (entry)
2315 			ssam_nf_refcount_dec_free(nf, n->event.reg, n->event.id);
2316 
2317 		mutex_unlock(&nf->lock);
2318 		return status;
2319 	}
2320 
2321 	if (entry) {
2322 		status = ssam_nf_refcount_enable(ctrl, entry, n->event.flags);
2323 		if (status) {
2324 			ssam_nfblk_remove(&n->base);
2325 			ssam_nf_refcount_dec_free(nf, n->event.reg, n->event.id);
2326 			mutex_unlock(&nf->lock);
2327 			synchronize_srcu(&nf_head->srcu);
2328 			return status;
2329 		}
2330 	}
2331 
2332 	mutex_unlock(&nf->lock);
2333 	return 0;
2334 }
2335 EXPORT_SYMBOL_GPL(ssam_notifier_register);
2336 
2337 /**
2338  * __ssam_notifier_unregister() - Unregister an event notifier.
2339  * @ctrl:    The controller the notifier has been registered on.
2340  * @n:       The event notifier to unregister.
2341  * @disable: Whether to disable the corresponding event on the EC.
2342  *
2343  * Unregister an event notifier. Decrement the usage counter of the associated
2344  * SAM event if the notifier is not marked as an observer. If the usage counter
2345  * reaches zero and ``disable`` equals ``true``, the event will be disabled.
2346  *
2347  * Useful for hot-removable devices, where communication may fail once the
2348  * device has been physically removed. In that case, specifying ``disable`` as
2349  * ``false`` avoids communication with the EC.
2350  *
2351  * Return: Returns zero on success, %-ENOENT if the given notifier block has
2352  * not been registered on the controller. If the given notifier block was the
2353  * last one associated with its specific event, returns the status of the
2354  * event-disable EC-command.
2355  */
2356 int __ssam_notifier_unregister(struct ssam_controller *ctrl, struct ssam_event_notifier *n,
2357 			       bool disable)
2358 {
2359 	u16 rqid = ssh_tc_to_rqid(n->event.id.target_category);
2360 	struct ssam_nf_refcount_entry *entry;
2361 	struct ssam_nf_head *nf_head;
2362 	struct ssam_nf *nf;
2363 	int status = 0;
2364 
2365 	if (!ssh_rqid_is_event(rqid))
2366 		return -EINVAL;
2367 
2368 	nf = &ctrl->cplt.event.notif;
2369 	nf_head = &nf->head[ssh_rqid_to_event(rqid)];
2370 
2371 	mutex_lock(&nf->lock);
2372 
2373 	if (!ssam_nfblk_find(nf_head, &n->base)) {
2374 		mutex_unlock(&nf->lock);
2375 		return -ENOENT;
2376 	}
2377 
2378 	/*
2379 	 * If this is an observer notifier, do not attempt to disable the
2380 	 * event, just remove it.
2381 	 */
2382 	if (!(n->flags & SSAM_EVENT_NOTIFIER_OBSERVER)) {
2383 		entry = ssam_nf_refcount_dec(nf, n->event.reg, n->event.id);
2384 		if (WARN_ON(!entry)) {
2385 			/*
2386 			 * If this does not return an entry, there's a logic
2387 			 * error somewhere: The notifier block is registered,
2388 			 * but the event refcount entry is not there. Remove
2389 			 * the notifier block anyways.
2390 			 */
2391 			status = -ENOENT;
2392 			goto remove;
2393 		}
2394 
2395 		status = ssam_nf_refcount_disable_free(ctrl, entry, n->event.flags, disable);
2396 	}
2397 
2398 remove:
2399 	ssam_nfblk_remove(&n->base);
2400 	mutex_unlock(&nf->lock);
2401 	synchronize_srcu(&nf_head->srcu);
2402 
2403 	return status;
2404 }
2405 EXPORT_SYMBOL_GPL(__ssam_notifier_unregister);
2406 
2407 /**
2408  * ssam_controller_event_enable() - Enable the specified event.
2409  * @ctrl:  The controller to enable the event for.
2410  * @reg:   The event registry to use for enabling the event.
2411  * @id:    The event ID specifying the event to be enabled.
2412  * @flags: The SAM event flags used for enabling the event.
2413  *
2414  * Increment the event reference count of the specified event. If the event has
2415  * not been enabled previously, it will be enabled by this call.
2416  *
2417  * Note: In general, ssam_notifier_register() with a non-observer notifier
2418  * should be preferred for enabling/disabling events, as this will guarantee
2419  * proper ordering and event forwarding in case of errors during event
2420  * enabling/disabling.
2421  *
2422  * Return: Returns zero on success, %-ENOSPC if the reference count for the
2423  * specified event has reached its maximum, %-ENOMEM if the corresponding event
2424  * entry could not be allocated. If this is the first time that this event has
2425  * been enabled (i.e. the reference count was incremented from zero to one by
2426  * this call), returns the status of the event-enable EC-command.
2427  */
2428 int ssam_controller_event_enable(struct ssam_controller *ctrl,
2429 				 struct ssam_event_registry reg,
2430 				 struct ssam_event_id id, u8 flags)
2431 {
2432 	u16 rqid = ssh_tc_to_rqid(id.target_category);
2433 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2434 	struct ssam_nf_refcount_entry *entry;
2435 	int status;
2436 
2437 	if (!ssh_rqid_is_event(rqid))
2438 		return -EINVAL;
2439 
2440 	mutex_lock(&nf->lock);
2441 
2442 	entry = ssam_nf_refcount_inc(nf, reg, id);
2443 	if (IS_ERR(entry)) {
2444 		mutex_unlock(&nf->lock);
2445 		return PTR_ERR(entry);
2446 	}
2447 
2448 	status = ssam_nf_refcount_enable(ctrl, entry, flags);
2449 	if (status) {
2450 		ssam_nf_refcount_dec_free(nf, reg, id);
2451 		mutex_unlock(&nf->lock);
2452 		return status;
2453 	}
2454 
2455 	mutex_unlock(&nf->lock);
2456 	return 0;
2457 }
2458 EXPORT_SYMBOL_GPL(ssam_controller_event_enable);
2459 
2460 /**
2461  * ssam_controller_event_disable() - Disable the specified event.
2462  * @ctrl:  The controller to disable the event for.
2463  * @reg:   The event registry to use for disabling the event.
2464  * @id:    The event ID specifying the event to be disabled.
2465  * @flags: The flags used when enabling the event.
2466  *
2467  * Decrement the reference count of the specified event. If the reference count
2468  * reaches zero, the event will be disabled.
2469  *
2470  * Note: In general, ssam_notifier_register()/ssam_notifier_unregister() with a
2471  * non-observer notifier should be preferred for enabling/disabling events, as
2472  * this will guarantee proper ordering and event forwarding in case of errors
2473  * during event enabling/disabling.
2474  *
2475  * Return: Returns zero on success, %-ENOENT if the given event has not been
2476  * enabled on the controller. If the reference count of the event reaches zero
2477  * during this call, returns the status of the event-disable EC-command.
2478  */
2479 int ssam_controller_event_disable(struct ssam_controller *ctrl,
2480 				  struct ssam_event_registry reg,
2481 				  struct ssam_event_id id, u8 flags)
2482 {
2483 	u16 rqid = ssh_tc_to_rqid(id.target_category);
2484 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2485 	struct ssam_nf_refcount_entry *entry;
2486 	int status;
2487 
2488 	if (!ssh_rqid_is_event(rqid))
2489 		return -EINVAL;
2490 
2491 	mutex_lock(&nf->lock);
2492 
2493 	entry = ssam_nf_refcount_dec(nf, reg, id);
2494 	if (!entry) {
2495 		mutex_unlock(&nf->lock);
2496 		return -ENOENT;
2497 	}
2498 
2499 	status = ssam_nf_refcount_disable_free(ctrl, entry, flags, true);
2500 
2501 	mutex_unlock(&nf->lock);
2502 	return status;
2503 }
2504 EXPORT_SYMBOL_GPL(ssam_controller_event_disable);
2505 
2506 /**
2507  * ssam_notifier_disable_registered() - Disable events for all registered
2508  * notifiers.
2509  * @ctrl: The controller for which to disable the notifiers/events.
2510  *
2511  * Disables events for all currently registered notifiers. In case of an error
2512  * (EC command failing), all previously disabled events will be restored and
2513  * the error code returned.
2514  *
2515  * This function is intended to disable all events prior to hibernation entry.
2516  * See ssam_notifier_restore_registered() to restore/re-enable all events
2517  * disabled with this function.
2518  *
2519  * Note that this function will not disable events for notifiers registered
2520  * after calling this function. It should thus be made sure that no new
2521  * notifiers are going to be added after this call and before the corresponding
2522  * call to ssam_notifier_restore_registered().
2523  *
2524  * Return: Returns zero on success. In case of failure returns the error code
2525  * returned by the failed EC command to disable an event.
2526  */
2527 int ssam_notifier_disable_registered(struct ssam_controller *ctrl)
2528 {
2529 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2530 	struct rb_node *n;
2531 	int status;
2532 
2533 	mutex_lock(&nf->lock);
2534 	for (n = rb_first(&nf->refcount); n; n = rb_next(n)) {
2535 		struct ssam_nf_refcount_entry *e;
2536 
2537 		e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2538 		status = ssam_ssh_event_disable(ctrl, e->key.reg,
2539 						e->key.id, e->flags);
2540 		if (status)
2541 			goto err;
2542 	}
2543 	mutex_unlock(&nf->lock);
2544 
2545 	return 0;
2546 
2547 err:
2548 	for (n = rb_prev(n); n; n = rb_prev(n)) {
2549 		struct ssam_nf_refcount_entry *e;
2550 
2551 		e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2552 		ssam_ssh_event_enable(ctrl, e->key.reg, e->key.id, e->flags);
2553 	}
2554 	mutex_unlock(&nf->lock);
2555 
2556 	return status;
2557 }
2558 
2559 /**
2560  * ssam_notifier_restore_registered() - Restore/re-enable events for all
2561  * registered notifiers.
2562  * @ctrl: The controller for which to restore the notifiers/events.
2563  *
2564  * Restores/re-enables all events for which notifiers have been registered on
2565  * the given controller. In case of a failure, the error is logged and the
2566  * function continues to try and enable the remaining events.
2567  *
2568  * This function is intended to restore/re-enable all registered events after
2569  * hibernation. See ssam_notifier_disable_registered() for the counter part
2570  * disabling the events and more details.
2571  */
2572 void ssam_notifier_restore_registered(struct ssam_controller *ctrl)
2573 {
2574 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2575 	struct rb_node *n;
2576 
2577 	mutex_lock(&nf->lock);
2578 	for (n = rb_first(&nf->refcount); n; n = rb_next(n)) {
2579 		struct ssam_nf_refcount_entry *e;
2580 
2581 		e = rb_entry(n, struct ssam_nf_refcount_entry, node);
2582 
2583 		/* Ignore errors, will get logged in call. */
2584 		ssam_ssh_event_enable(ctrl, e->key.reg, e->key.id, e->flags);
2585 	}
2586 	mutex_unlock(&nf->lock);
2587 }
2588 
2589 /**
2590  * ssam_notifier_is_empty() - Check if there are any registered notifiers.
2591  * @ctrl: The controller to check on.
2592  *
2593  * Return: Returns %true if there are currently no notifiers registered on the
2594  * controller, %false otherwise.
2595  */
2596 static bool ssam_notifier_is_empty(struct ssam_controller *ctrl)
2597 {
2598 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2599 	bool result;
2600 
2601 	mutex_lock(&nf->lock);
2602 	result = ssam_nf_refcount_empty(nf);
2603 	mutex_unlock(&nf->lock);
2604 
2605 	return result;
2606 }
2607 
2608 /**
2609  * ssam_notifier_unregister_all() - Unregister all currently registered
2610  * notifiers.
2611  * @ctrl: The controller to unregister the notifiers on.
2612  *
2613  * Unregisters all currently registered notifiers. This function is used to
2614  * ensure that all notifiers will be unregistered and associated
2615  * entries/resources freed when the controller is being shut down.
2616  */
2617 static void ssam_notifier_unregister_all(struct ssam_controller *ctrl)
2618 {
2619 	struct ssam_nf *nf = &ctrl->cplt.event.notif;
2620 	struct ssam_nf_refcount_entry *e, *n;
2621 
2622 	mutex_lock(&nf->lock);
2623 	rbtree_postorder_for_each_entry_safe(e, n, &nf->refcount, node) {
2624 		/* Ignore errors, will get logged in call. */
2625 		ssam_ssh_event_disable(ctrl, e->key.reg, e->key.id, e->flags);
2626 		kfree(e);
2627 	}
2628 	nf->refcount = RB_ROOT;
2629 	mutex_unlock(&nf->lock);
2630 }
2631 
2632 
2633 /* -- Wakeup IRQ. ----------------------------------------------------------- */
2634 
2635 static irqreturn_t ssam_irq_handle(int irq, void *dev_id)
2636 {
2637 	struct ssam_controller *ctrl = dev_id;
2638 
2639 	ssam_dbg(ctrl, "pm: wake irq triggered\n");
2640 
2641 	/*
2642 	 * Note: Proper wakeup detection is currently unimplemented.
2643 	 *       When the EC is in display-off or any other non-D0 state, it
2644 	 *       does not send events/notifications to the host. Instead it
2645 	 *       signals that there are events available via the wakeup IRQ.
2646 	 *       This driver is responsible for calling back to the EC to
2647 	 *       release these events one-by-one.
2648 	 *
2649 	 *       This IRQ should not cause a full system resume by its own.
2650 	 *       Instead, events should be handled by their respective subsystem
2651 	 *       drivers, which in turn should signal whether a full system
2652 	 *       resume should be performed.
2653 	 *
2654 	 * TODO: Send GPIO callback command repeatedly to EC until callback
2655 	 *       returns 0x00. Return flag of callback is "has more events".
2656 	 *       Each time the command is sent, one event is "released". Once
2657 	 *       all events have been released (return = 0x00), the GPIO is
2658 	 *       re-armed. Detect wakeup events during this process, go back to
2659 	 *       sleep if no wakeup event has been received.
2660 	 */
2661 
2662 	return IRQ_HANDLED;
2663 }
2664 
2665 /**
2666  * ssam_irq_setup() - Set up SAM EC wakeup-GPIO interrupt.
2667  * @ctrl: The controller for which the IRQ should be set up.
2668  *
2669  * Set up an IRQ for the wakeup-GPIO pin of the SAM EC. This IRQ can be used
2670  * to wake the device from a low power state.
2671  *
2672  * Note that this IRQ can only be triggered while the EC is in the display-off
2673  * state. In this state, events are not sent to the host in the usual way.
2674  * Instead the wakeup-GPIO gets pulled to "high" as long as there are pending
2675  * events and these events need to be released one-by-one via the GPIO
2676  * callback request, either until there are no events left and the GPIO is
2677  * reset, or all at once by transitioning the EC out of the display-off state,
2678  * which will also clear the GPIO.
2679  *
2680  * Not all events, however, should trigger a full system wakeup. Instead the
2681  * driver should, if necessary, inspect and forward each event to the
2682  * corresponding subsystem, which in turn should decide if the system needs to
2683  * be woken up. This logic has not been implemented yet, thus wakeup by this
2684  * IRQ should be disabled by default to avoid spurious wake-ups, caused, for
2685  * example, by the remaining battery percentage changing. Refer to comments in
2686  * this function and comments in the corresponding IRQ handler for more
2687  * details on how this should be implemented.
2688  *
2689  * See also ssam_ctrl_notif_display_off() and ssam_ctrl_notif_display_off()
2690  * for functions to transition the EC into and out of the display-off state as
2691  * well as more details on it.
2692  *
2693  * The IRQ is disabled by default and has to be enabled before it can wake up
2694  * the device from suspend via ssam_irq_arm_for_wakeup(). On teardown, the IRQ
2695  * should be freed via ssam_irq_free().
2696  */
2697 int ssam_irq_setup(struct ssam_controller *ctrl)
2698 {
2699 	struct device *dev = ssam_controller_device(ctrl);
2700 	struct gpio_desc *gpiod;
2701 	int irq;
2702 	int status;
2703 
2704 	/*
2705 	 * The actual GPIO interrupt is declared in ACPI as TRIGGER_HIGH.
2706 	 * However, the GPIO line only gets reset by sending the GPIO callback
2707 	 * command to SAM (or alternatively the display-on notification). As
2708 	 * proper handling for this interrupt is not implemented yet, leaving
2709 	 * the IRQ at TRIGGER_HIGH would cause an IRQ storm (as the callback
2710 	 * never gets sent and thus the line never gets reset). To avoid this,
2711 	 * mark the IRQ as TRIGGER_RISING for now, only creating a single
2712 	 * interrupt, and let the SAM resume callback during the controller
2713 	 * resume process clear it.
2714 	 */
2715 	const int irqf = IRQF_ONESHOT | IRQF_TRIGGER_RISING | IRQF_NO_AUTOEN;
2716 
2717 	gpiod = gpiod_get(dev, "ssam_wakeup-int", GPIOD_ASIS);
2718 	if (IS_ERR(gpiod))
2719 		return PTR_ERR(gpiod);
2720 
2721 	irq = gpiod_to_irq(gpiod);
2722 	gpiod_put(gpiod);
2723 
2724 	if (irq < 0)
2725 		return irq;
2726 
2727 	status = request_threaded_irq(irq, NULL, ssam_irq_handle, irqf,
2728 				      "ssam_wakeup", ctrl);
2729 	if (status)
2730 		return status;
2731 
2732 	ctrl->irq.num = irq;
2733 	return 0;
2734 }
2735 
2736 /**
2737  * ssam_irq_free() - Free SAM EC wakeup-GPIO interrupt.
2738  * @ctrl: The controller for which the IRQ should be freed.
2739  *
2740  * Free the wakeup-GPIO IRQ previously set-up via ssam_irq_setup().
2741  */
2742 void ssam_irq_free(struct ssam_controller *ctrl)
2743 {
2744 	free_irq(ctrl->irq.num, ctrl);
2745 	ctrl->irq.num = -1;
2746 }
2747 
2748 /**
2749  * ssam_irq_arm_for_wakeup() - Arm the EC IRQ for wakeup, if enabled.
2750  * @ctrl: The controller for which the IRQ should be armed.
2751  *
2752  * Sets up the IRQ so that it can be used to wake the device. Specifically,
2753  * this function enables the irq and then, if the device is allowed to wake up
2754  * the system, calls enable_irq_wake(). See ssam_irq_disarm_wakeup() for the
2755  * corresponding function to disable the IRQ.
2756  *
2757  * This function is intended to arm the IRQ before entering S2idle suspend.
2758  *
2759  * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must
2760  * be balanced.
2761  */
2762 int ssam_irq_arm_for_wakeup(struct ssam_controller *ctrl)
2763 {
2764 	struct device *dev = ssam_controller_device(ctrl);
2765 	int status;
2766 
2767 	enable_irq(ctrl->irq.num);
2768 	if (device_may_wakeup(dev)) {
2769 		status = enable_irq_wake(ctrl->irq.num);
2770 		if (status) {
2771 			ssam_err(ctrl, "failed to enable wake IRQ: %d\n", status);
2772 			disable_irq(ctrl->irq.num);
2773 			return status;
2774 		}
2775 
2776 		ctrl->irq.wakeup_enabled = true;
2777 	} else {
2778 		ctrl->irq.wakeup_enabled = false;
2779 	}
2780 
2781 	return 0;
2782 }
2783 
2784 /**
2785  * ssam_irq_disarm_wakeup() - Disarm the wakeup IRQ.
2786  * @ctrl: The controller for which the IRQ should be disarmed.
2787  *
2788  * Disarm the IRQ previously set up for wake via ssam_irq_arm_for_wakeup().
2789  *
2790  * This function is intended to disarm the IRQ after exiting S2idle suspend.
2791  *
2792  * Note: calls to ssam_irq_arm_for_wakeup() and ssam_irq_disarm_wakeup() must
2793  * be balanced.
2794  */
2795 void ssam_irq_disarm_wakeup(struct ssam_controller *ctrl)
2796 {
2797 	int status;
2798 
2799 	if (ctrl->irq.wakeup_enabled) {
2800 		status = disable_irq_wake(ctrl->irq.num);
2801 		if (status)
2802 			ssam_err(ctrl, "failed to disable wake IRQ: %d\n", status);
2803 
2804 		ctrl->irq.wakeup_enabled = false;
2805 	}
2806 	disable_irq(ctrl->irq.num);
2807 }
2808