Added logger function

Author: lexus2k

Makefile.common

@@ -79,6 +79,7 @@ OBJ_LIB += \
         src/proto/hdlc/high_level/hdlc.o \
         src/proto/hdlc/low_level/hdlc.o \
         src/proto/fd/tiny_fd.o \
+        src/proto/fd/tiny_fd_proto_logger.o \
         src/proto/fd/tiny_fd_frames.o \
         src/hal/tiny_list.o \
         src/hal/tiny_debug.o \

README.md

@@ -39,19 +39,20 @@ Tiny Protocol is NOT an application layer protocol, although, for example, it ca
 
 ## Key Features
 
-Main features:
- * Hot plug/unplug support for ABM (peer to peer).
- * Connection autorecover for Full duplex (both for ABM and NRM modes) and Light protocols (with enabled crc)
- * Error detection: Simple 8-bit checksum (sum of bytes), FCS16 (CCITT-16), FCS32 (CCITT-32)
- * Platform independent hdlc framing implementation (hdlc low level API: hdlc_ll_xxxx)
- * Easy to use Light protcol - analogue of a SLIP protcol (tiny_light_xxxx API, see examples)
- * Full-duplex protocol (tiny_fd_xxxx true RFC 1662 implementation, supports confirmation, frames retransmissions: ABM and NRM modes )
- * one to one and one to many modes
- * Frames of maximum 32K or 2G size (payload limit depends on platfrom).
- * Low SRAM consumption (starts at 60 bytes).
- * Low Flash consumption (starts at 1.2KiB, features can be disabled and enabled at compilation time)
- * No dynamic memory allocation!
- * Special serial loopback tool for debug purposes and performance testing (ABM mode only)
+**Main Features:**
+
+- **Hot Plug/Unplug Support:** Seamless connection and disconnection handling for ABM (peer-to-peer) mode.
+- **Comprehensive Logging:** HDLC full-duplex log function simplifies protocol debugging by capturing all packets sent or received by a peer, including data, service (S), and unnumbered (U) frames.
+- **Automatic Connection Recovery:** Robust autorecovery for full-duplex (ABM and NRM modes) and Light protocols (with CRC enabled).
+- **Error Detection:** Supports simple 8-bit checksum, FCS16 (CCITT-16), and FCS32 (CCITT-32) for reliable communication.
+- **Platform-Independent HDLC Framing:** Low-level HDLC API (`hdlc_ll_xxxx`) ensures portability across platforms.
+- **Easy-to-Use Light Protocol:** Lightweight protocol similar to SLIP (`tiny_light_xxxx` API), see examples for usage.
+- **Full-Duplex Protocol:** True RFC 1662 implementation (`tiny_fd_xxxx`), supporting acknowledgments, frame retransmissions, and both ABM and NRM modes.
+- **Flexible Topologies:** Supports both one-to-one and one-to-many communication modes.
+- **Large Frame Support:** Handles frames up to 32K or 2G in size (payload limit depends on platform).
+- **Low Resource Consumption:** Minimal SRAM usage (starting at 60 bytes) and flash footprint (starting at 1.3 KiB). Features can be enabled or disabled at compile time.
+- **No Dynamic Memory Allocation:** Ensures predictable memory usage.
+- **Serial Loopback Tool:** Dedicated tool for debugging and performance testing (ABM mode only).
 
 ## Supported platforms
 

src/proto/fd/tiny_fd.c

@@ -64,79 +64,6 @@ static uint8_t __switch_to_next_peer(tiny_fd_handle_t handle)
     return start_peer != handle->next_peer;
 }
 
-#if defined(TINY_FD_DEBUG) && defined(TINY_FILE_LOGGING)
-///////////////////////////////////////////////////////////////////////////////
-
-static char __get_frame_type(uint8_t control)
-{
-    if ((control & HDLC_I_FRAME_MASK) == HDLC_I_FRAME_BITS)
-    {
-        return 'I';
-    }
-    else if ((control & HDLC_S_FRAME_MASK) == HDLC_S_FRAME_BITS)
-    {
-        return 'S';
-    }
-    return 'U';
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-static const char *__get_frame_type_str(uint8_t control)
-{
-    char type = __get_frame_type(control);
-    if (type == 'I') {
-        return "    ";
-    }
-    else if (type == 'S') {
-        switch (control & HDLC_S_FRAME_TYPE_MASK)
-        {
-            case HDLC_S_FRAME_TYPE_RR:  return "  RR";
-            case HDLC_S_FRAME_TYPE_REJ: return " REJ";
-            default:                    return " UNK";
-        }
-    }
-    switch (control & HDLC_U_FRAME_TYPE_MASK)
-    {
-        case HDLC_U_FRAME_TYPE_UA:   return "  UA";
-        case HDLC_U_FRAME_TYPE_FRMR: return "FRMR";
-        case HDLC_U_FRAME_TYPE_RSET: return "RSET";
-        case HDLC_U_FRAME_TYPE_SABM: return "SABM";
-        case HDLC_U_FRAME_TYPE_SNRM: return "SNRM";
-        case HDLC_U_FRAME_TYPE_DISC: return "DISC";
-        default:                     return " UNK";
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-static uint8_t __get_frame_sequence(uint8_t control)
-{
-    char type = __get_frame_type(control);
-    switch (type)
-    {
-        case 'I': return (control >> 1) & 0x07;
-        case 'S':
-        case 'U':
-        default: return 0;
-    }
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-static uint8_t __get_awaiting_sequence(uint8_t control)
-{
-    char type = __get_frame_type(control);
-    switch (type)
-    {
-        case 'I': return control >> 5;
-        case 'S': return control >> 5;
-        case 'U':
-        default: return 0;
-    }
-}
-#endif // TINY_FD_DEBUG && TINY_FILE_LOGGING
-
 ///////////////////////////////////////////////////////////////////////////////
 
 #if 0
@@ -232,8 +159,7 @@ static void on_frame_read(void *user_data, uint8_t *data, int len)
         LOG(TINY_LOG_WRN, "%s: received too small frame\n", "FD");
         return;
     }
-    FILE_LOG((uintptr_t)handle, " IN", __get_frame_type(data[1]), __get_frame_type_str(data[1]),
-            __get_frame_sequence(data[1]), __get_awaiting_sequence(data[1]));
+    __tiny_fd_log_frame(handle, TINY_FD_FRAME_DIRECTION_IN, data, len);
     uint8_t peer = __address_field_to_peer( handle, ((uint8_t *)data)[0] );
     if ( peer == 0xFF )
     {
@@ -444,6 +370,7 @@ int tiny_fd_init(tiny_fd_handle_t *handle, tiny_fd_init_t *init)
     protocol->on_read_cb = init->on_read_cb;
     protocol->on_send_cb = init->on_send_cb;
     protocol->on_connect_event_cb = init->on_connect_event_cb;
+    protocol->log_frame_cb = init->log_frame_cb;
     protocol->send_timeout = init->send_timeout;
     // By default assign primary address
     protocol->addr = (init->addr ? (init->addr << 2) : HDLC_PRIMARY_ADDR ) | HDLC_E_BIT;
@@ -594,9 +521,7 @@ static uint8_t *tiny_fd_get_next_frame_to_send(tiny_fd_handle_t handle, int *len
         header->control |= HDLC_P_BIT;
         handle->last_marker_ts = tiny_millis();
         handle->peers[peer].last_ka_ts = tiny_millis();
-        FILE_LOG((uintptr_t)handle, "OUT", __get_frame_type(header->control),
-                 __get_frame_type_str(header->control),
-                 __get_frame_sequence(header->control), __get_awaiting_sequence(header->control));
+        __tiny_fd_log_frame(handle, TINY_FD_FRAME_DIRECTION_OUT, data, *len);
     }
     tiny_mutex_unlock(&handle->frames.mutex);
     return data;

src/proto/fd/tiny_fd.h

@@ -1,5 +1,5 @@
 /*
-    Copyright 2019-2024 (C) Alexey Dynda
+    Copyright 2019-2025 (C) Alexey Dynda
 
     This file is part of Tiny Protocol Library.
 
@@ -78,6 +78,9 @@ extern "C"
         TINY_FD_MODE_ARM = 0x02,
     };
 
+    /** 
+     * Forward declaration of tiny_fd_data_t structure.
+     */
     struct tiny_fd_data_t;
 
     /**
@@ -86,6 +89,71 @@ extern "C"
      */
     typedef struct tiny_fd_data_t *tiny_fd_handle_t;
 
+    /**
+     * Enumeration of frame types used in Tiny Full Duplex protocol.
+     */
+    typedef enum
+    {
+        TINY_FD_FRAME_TYPE_I = 0x00, ///< I-frame
+        TINY_FD_FRAME_TYPE_S = 0x01, ///< S-frame
+        TINY_FD_FRAME_TYPE_U = 0x02, ///< U-frame
+    } tiny_fd_frame_type_t;
+
+    /**
+     * Enumeration of frame subtypes used in Tiny Full Duplex protocol.
+     * These subtypes are used for S-frames and U-frames.
+     * The I-frames do not have subtypes, so this enumeration is not used for I-frames.
+     */
+    typedef enum
+    {
+        TINY_FD_FRAME_SUBTYPE_RR = 0x00, ///< S-frame subtype RR
+        TINY_FD_FRAME_SUBTYPE_REJ = 0x08, ///< S-frame subtype REJ
+
+        TINY_FD_FRAME_SUBTYPE_UA = 0x60, ///< U-frame subtype UA
+        TINY_FD_FRAME_SUBTYPE_FRMR = 0x84, ///< U-frame subtype FRMR
+        TINY_FD_FRAME_SUBTYPE_RSET = 0x8C, ///< U-frame subtype RSET
+        TINY_FD_FRAME_SUBTYPE_SABM = 0x2C, ///< U-frame subtype SABM
+        TINY_FD_FRAME_SUBTYPE_SNRM = 0x80, ///< U-frame subtype SNRM
+        TINY_FD_FRAME_SUBTYPE_DISC = 0x40, ///< U-frame subtype DISC
+    } tiny_fd_frame_subtype_t;
+
+    /**
+     * Enumeration of frame directions used in Tiny Full Duplex protocol.
+     */
+    typedef enum
+    {
+        TINY_FD_FRAME_DIRECTION_IN = 0x00, ///< Frame is incoming
+        TINY_FD_FRAME_DIRECTION_OUT = 0x01, ///< Frame is outgoing
+    } tiny_fd_frame_direction_t;
+
+    /**
+     * tiny_fd_log_frame_cb_t is a callback function, which is called every time frame is sent or received.
+     * This callback is useful for debugging purposes.
+     * 
+     * The main difference between this callback and on_frame_read_cb_t / on_frame_send_cb_t is that
+     * this callback is called for every frame, regardless of whether it is sent or received: I-frames, S-frames or U-frames.
+     * It provides detailed information about the frame, including its type, subtype, sequence numbers and data.
+     * 
+     * @param handle handle of Tiny.
+     * @param direction direction of the frame, can be TINY_FD_FRAME_DIRECTION_IN or TINY_FD_FRAME_DIRECTION_OUT.
+     * @param frame_type type of the frame, can be TINY_FD_FRAME_TYPE_I, TINY_FD_FRAME_TYPE_S or TINY_FD_FRAME_TYPE_U.
+     * @param frame_subtype subtype of the frame, can be TINY_FD_FRAME_SUBTYPE_RR, TINY_FD_FRAME_SUBTYPE_REJ,
+     *                     TINY_FD_FRAME_SUBTYPE_UA, TINY_FD_FRAME_SUBTYPE_FRMR, TINY_FD_FRAME_SUBTYPE_RSET,
+     *                     TINY_FD_FRAME_SUBTYPE_SABM, TINY_FD_FRAME_SUBTYPE_SNRM or TINY_FD_FRAME_SUBTYPE_DISC.
+     * @param ns N(S) sequence number of the frame.
+     * @param nr N(R) sequence number of the frame.
+     * @param data pointer to the frame data.
+     * @param len length of the frame data.
+     */
+    typedef void (*tiny_fd_log_frame_cb_t)(tiny_fd_handle_t handle,
+                       tiny_fd_frame_direction_t direction,
+                       tiny_fd_frame_type_t frame_type,
+                       tiny_fd_frame_subtype_t frame_subtype,
+                       uint8_t ns,
+                       uint8_t nr,
+                       const uint8_t *data,
+                       int len);
+   
     /**
      * This structure is used for initialization of Tiny Full Duplex protocol.
      */
@@ -153,6 +221,13 @@ extern "C"
          */
         on_connect_event_cb_t on_connect_event_cb;
 
+        /**
+         * Callback to log frames. Can be NULL.
+         * If this callback is set, it will be called for every frame sent or received.
+         * This is useful for debugging purposes.
+         */
+        tiny_fd_log_frame_cb_t log_frame_cb;
+
         /**
          * Local station address. The field has meaning only for secondary stations.
          * For primary stations please, leave this field as 0.

src/proto/fd/tiny_fd_int.h

@@ -118,6 +118,8 @@ extern "C"
         on_frame_send_cb_t on_send_cb;
         /// Callback to get connect/disconnect notification
         on_connect_event_cb_t on_connect_event_cb;
+        /// Callback to log frames
+        tiny_fd_log_frame_cb_t log_frame_cb;
         /// hdlc information
         hdlc_ll_handle_t _hdlc;
         /// Timeout for operations with acknowledge
@@ -148,6 +150,12 @@ extern "C"
         void *user_data;
     } tiny_fd_data_t;
 
+    extern void __tiny_fd_log_frame(
+                        tiny_fd_handle_t handle,
+                       tiny_fd_frame_direction_t direction,
+                       const uint8_t *data,
+                       int len);
+
 #ifdef __cplusplus
 }
 #endif