diff options
author | Phil Elwell <phil@raspberrypi.com> | 2022-12-22 15:15:53 +0100 |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@linuxfoundation.org> | 2023-01-17 19:21:57 +0100 |
commit | c478aa127eaf9ba67c0da877a67269039f7e94b6 (patch) | |
tree | 4f0fb0822995243fce7986af5d7aa7faa685d262 | |
parent | 72b74b646bdd61a4954b3225337d5f735a41761d (diff) | |
download | linux-stable-c478aa127eaf9ba67c0da877a67269039f7e94b6.tar.gz linux-stable-c478aa127eaf9ba67c0da877a67269039f7e94b6.tar.bz2 linux-stable-c478aa127eaf9ba67c0da877a67269039f7e94b6.zip |
staging: vchiq_core: Add comments to remote event parts
struct remote_event and the related functions remote_event_*() provides
a higher function between ARM core and VPU. It's very helpful for a
reviewer to have explaining comments about these parts.
Signed-off-by: Phil Elwell <phil@raspberrypi.com>
Signed-off-by: Stefan Wahren <stefan.wahren@i2se.com>
Link: https://lore.kernel.org/r/20221222141553.138563-1-stefan.wahren@i2se.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-rw-r--r-- | drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.c | 10 | ||||
-rw-r--r-- | drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h | 18 |
2 files changed, 28 insertions, 0 deletions
diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.c b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.c index 45ed30bfdbf5..2571a3742745 100644 --- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.c +++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.c @@ -498,6 +498,7 @@ vchiq_set_conn_state(struct vchiq_state *state, enum vchiq_connstate newstate) vchiq_platform_conn_state_changed(state, oldstate, newstate); } +/* This initialises a single remote_event, and the associated wait_queue. */ static inline void remote_event_create(wait_queue_head_t *wq, struct remote_event *event) { @@ -536,6 +537,10 @@ remote_event_wait(wait_queue_head_t *wq, struct remote_event *event) return 1; } +/* + * Acknowledge that the event has been signalled, and wake any waiters. Usually + * called as a result of the doorbell being rung. + */ static inline void remote_event_signal_local(wait_queue_head_t *wq, struct remote_event *event) { @@ -544,6 +549,7 @@ remote_event_signal_local(wait_queue_head_t *wq, struct remote_event *event) wake_up_all(wq); } +/* Check if a single event has been signalled, waking the waiters if it has. */ static inline void remote_event_poll(wait_queue_head_t *wq, struct remote_event *event) { @@ -551,6 +557,10 @@ remote_event_poll(wait_queue_head_t *wq, struct remote_event *event) remote_event_signal_local(wq, event); } +/* + * VCHIQ used a small, fixed number of remote events. It is simplest to + * enumerate them here for polling. + */ void remote_event_pollall(struct vchiq_state *state) { diff --git a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h index 8b4a38f5b3f2..fd6c95e91436 100644 --- a/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h +++ b/drivers/staging/vc04_services/interface/vchiq_arm/vchiq_core.h @@ -166,6 +166,24 @@ struct vchiq_bulk_queue { struct vchiq_bulk bulks[VCHIQ_NUM_SERVICE_BULKS]; }; +/* + * Remote events provide a way of presenting several virtual doorbells to a + * peer (ARM host to VPU) using only one physical doorbell. They can be thought + * of as a way for the peer to signal a semaphore, in this case implemented as + * a workqueue. + * + * Remote events remain signalled until acknowledged by the receiver, and they + * are non-counting. They are designed in such a way as to minimise the number + * of interrupts and avoid unnecessary waiting. + * + * A remote_event is as small data structures that live in shared memory. It + * comprises two booleans - armed and fired: + * + * The sender sets fired when they signal the receiver. + * If fired is set, the receiver has been signalled and need not wait. + * The receiver sets the armed field before they begin to wait. + * If armed is set, the receiver is waiting and wishes to be woken by interrupt. + */ struct remote_event { int armed; int fired; |