From 6a263a1959c7affb8db2d82b77835a2ed02b2f95 Mon Sep 17 00:00:00 2001
From: Jeremy Boynes <jeremy@boynes.com>
Date: Thu, 2 Nov 2023 13:39:21 +0000
Subject: [PATCH] Add documentation for CAN API
---
api/HardwareCAN.h | 46 +++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 45 insertions(+), 1 deletion(-)
diff --git a/api/HardwareCAN.h b/api/HardwareCAN.h
index 6dc87ebc..a5b87604 100644
--- a/api/HardwareCAN.h
+++ b/api/HardwareCAN.h
@@ -44,12 +44,56 @@ class HardwareCAN
virtual ~HardwareCAN() {}
+ /**
+ * Initialize the CAN controller.
+ *
+ * @param can_bitrate the bus bit rate
+ * @return true if initialization succeeded and the controller is operational
+ */
virtual bool begin(CanBitRate const can_bitrate) = 0;
- virtual void end() = 0;
+ /**
+ * Disable the CAN controller.
+ *
+ * Whether any messages that are buffered will be sent is _implementation defined_.
+ */
+ virtual void end() = 0;
+ /**
+ * Enqueue a message for transmission to the CAN bus.
+ *
+ * This call returns when the message has been enqueued for transmission.
+ * Due to bus arbitration and error recovery there may be a substantial delay
+ * before the message is actually sent.
+ *
+ * An implementation must ensure that all messages with the same CAN priority
+ * are sent in the order in which they are enqueued.
+ *
+ * It is _implementation defined_ whether multiple messages can be enqueued
+ * for transmission, and if messages with higher CAN priority can preempt the
+ * transmission of previously enqueued messages. The default configuration for
+ * and implementation should not allow multiple messages to be enqueued.
+ *
+ * @param msg the message to send
+ * @return 1 if the message was enqueued, an _implementation defined_ error code < 0 if there was an error
+ * @todo define specific error codes, especially "message already pending"
+ */
virtual int write(CanMsg const &msg) = 0;
+
+ /**
+ * Determine if any messages have been received and buffered.
+ *
+ * @return the number of unread messages that have been received
+ */
virtual size_t available() = 0;
+
+ /**
+ * Returns the first message received, or an empty message if none are available.
+ *
+ * Messages must be returned in the order received.
+ *
+ * @return the first message in the receive buffer
+ */
virtual CanMsg read() = 0;
};