From c478aa127eaf9ba67c0da877a67269039f7e94b6 Mon Sep 17 00:00:00 2001 From: Phil Elwell Date: Thu, 22 Dec 2022 15:15:53 +0100 Subject: 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 Signed-off-by: Stefan Wahren Link: https://lore.kernel.org/r/20221222141553.138563-1-stefan.wahren@i2se.com Signed-off-by: Greg Kroah-Hartman --- .../vc04_services/interface/vchiq_arm/vchiq_core.c | 10 ++++++++++ .../vc04_services/interface/vchiq_arm/vchiq_core.h | 18 ++++++++++++++++++ 2 files changed, 28 insertions(+) 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; -- cgit v1.2.3