From 9fc527b8b01847b16a8aa577dec4c6d9401a2ef0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonny=20Sv=C3=A4rd?= <jonny.svaerd@arm.com>
Date: Mon, 16 Nov 2020 16:18:07 +0100
Subject: Add basic MHU drivers

Add MHUv2 doorbell driver implementation
Add MHU doorbell driver for Juno board
Add a dummy MHU driver
Add some comments to the mailbox header file

Change-Id: I0950a7ca3afeec88ca691ca2486022dfbb3319b8
---
 drivers/mailbox/include/mailbox.hpp | 46 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

(limited to 'drivers/mailbox/include/mailbox.hpp')

diff --git a/drivers/mailbox/include/mailbox.hpp b/drivers/mailbox/include/mailbox.hpp
index 465503e..f3a2dc4 100644
--- a/drivers/mailbox/include/mailbox.hpp
+++ b/drivers/mailbox/include/mailbox.hpp
@@ -25,19 +25,63 @@
 
 namespace Mailbox {
 
+/**
+ * The Mailbox parent class
+ *
+ * Intended to be implemented by a driver subclass, see MHU_v2 driver as example.
+ */
 class Mailbox {
 public:
+    /**
+     * Constructor/Destructor
+     */
     Mailbox();
     virtual ~Mailbox();
-    virtual bool sendMessage()   = 0;
+
+    /**
+     * Intended to trigger an interrupt to an external block
+     * MUST be implemented by subclass.
+     */
+    virtual bool sendMessage() = 0;
+
+    /**
+     * Intended to be called when Cortex M has received an
+     * interrupt/event from mailbox/mhu. If an interrupt needs to be cleared,
+     * this is a good place to do that. MUST call notify().
+     * MUST be implemented by subclass.
+     */
     virtual void handleMessage() = 0;
+
+    /**
+     * Can be used to verify that hardware versions match expected versions
+     * CAN be implemented by subclass, optional. Default impl returns true.
+     */
     virtual bool verifyHardware();
+
+    /**
+     * Function signature for callbacks
+     */
     typedef void (*CallbackFptr)(void *userArg);
+
+    /**
+     * Register a callback to be called when a message is received.
+     */
     void registerCallback(CallbackFptr callback, void *userArg);
+
+    /**
+     * Remove a specific callback from the callback list.
+     */
     void deregisterCallback(CallbackFptr callback, void *userArg);
 
 protected:
+    /**
+     * Calls every registered callback when a message has been received.
+     */
     void notify();
+
+    /**
+     * Helper functions
+     */
     uint32_t read32(volatile uint32_t *baseAddr, const uint32_t offset);
     void write32(volatile uint32_t *baseAddr, const uint32_t offset, const uint32_t value);
 
-- 
cgit v1.2.1