From a933e6a86d28357e84f779c859d8435ca6924fb7 Mon Sep 17 00:00:00 2001
From: Phil Greenland <40036098+pgreenland@users.noreply.github.com>
Date: Wed, 21 Feb 2024 21:59:17 +0000
Subject: [PATCH] Allow transmissions to be retried if the controller was busy
 (#26)

* Allow transmissions to be retried if the controller was busy / out of buffer space.

* Fixed comments.

---------

Co-authored-by: Simon Cahill <simon@simonc.eu>
---
 README.md       |  5 ++++-
 isotp.c         |  2 ++
 isotp_defines.h |  1 +
 isotp_user.h    | 14 ++++++++++----
 4 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5705737..faaff68 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,10 @@ First, create some [shim](https://en.wikipedia.org/wiki/Shim_(computing)) functi
 ```C
     /* required, this must send a single CAN message with the given arbitration
      * ID (i.e. the CAN message ID) and data. The size will never be more than 8
-     * bytes. */
+     * bytes. Should return ISOTP_RET_OK if frame sent successfully.
+     * May return ISOTP_RET_NOSPACE if the frame could not be sent but may be
+     * retried later. Should return ISOTP_RET_ERROR in case frame could not be sent.
+     */
     int  isotp_user_send_can(const uint32_t arbitration_id,
                              const uint8_t* data, const uint8_t size) {
         // ...
diff --git a/isotp.c b/isotp.c
index 1936b21..b5e049b 100644
--- a/isotp.c
+++ b/isotp.c
@@ -484,6 +484,8 @@ void isotp_poll(IsoTpLink *link) {
                 if (link->send_offset >= link->send_size) {
                     link->send_status = ISOTP_SEND_STATUS_IDLE;
                 }
+            } else if (ISOTP_RET_NOSPACE == ret) {
+                /* shim reported that it isn't able to send a frame at present, retry on next call */
             } else {
                 link->send_status = ISOTP_SEND_STATUS_ERROR;
             }
diff --git a/isotp_defines.h b/isotp_defines.h
index b6948b5..1dfe819 100644
--- a/isotp_defines.h
+++ b/isotp_defines.h
@@ -42,6 +42,7 @@
 #define ISOTP_RET_NO_DATA      -5
 #define ISOTP_RET_TIMEOUT      -6
 #define ISOTP_RET_LENGTH       -7
+#define ISOTP_RET_NOSPACE      -8
 
 /* return logic true if 'a' is after 'b' */
 #define IsoTpTimeAfter(a,b) ((int32_t)((int32_t)(b) - (int32_t)(a)) < 0)
diff --git a/isotp_user.h b/isotp_user.h
index ed40337..1104371 100644
--- a/isotp_user.h
+++ b/isotp_user.h
@@ -7,15 +7,21 @@
 extern "C" {
 #endif
 
-/* user implemented, print debug message */
+/** @brief user implemented, print debug message */
 void isotp_user_debug(const char* message, ...);
 
-/* user implemented, send can message. should return ISOTP_RET_OK when success.
-*/
+/**
+ * @brief user implemented, send can message. should return ISOTP_RET_OK when success.
+ * 
+ * @return may return ISOTP_RET_NOSPACE if the CAN transfer should be retried later
+ * or ISOTP_RET_ERROR if transmission couldn't be completed
+ */
 int  isotp_user_send_can(const uint32_t arbitration_id,
                          const uint8_t* data, const uint8_t size);
 
-/* user implemented, get microsecond */
+/**
+ * @brief user implemented, gets the amount of time passed since the last call in microseconds
+ */
 uint32_t isotp_user_get_us(void);
 
 #ifdef __cplusplus