nuttx/can: add read watermark

This provides an optional way to limit number of frames to be copied to
the buffer on read operation. The idea is to allow not only binary
decision if more than one frame can be read but a more granular control.

The size of the buffer itself can't be used for this purpose because
even on plain CAN up three small frames can fit into buffer prepared for
a full sized frame. The explicit change of the behavior of course is not
desirable but having ability to control this is advantageous.

The motivation behind this is the compatibility with socket CAN. It is
easier to port applications to NuttX's CAN driver if only one frame is
provided at the time. This is achieved by setting watermark to zero.

This solution was suggested by Pavel Pisa <[email protected]> as a more
versatile variant of plain boolean disabling the multiple frame
retrieval.

Signed-off-by: Karel Kočí <[email protected]>

Author: Cynerd

drivers/can/can.c

@@ -193,6 +193,7 @@ static FAR struct can_reader_s *init_can_reader(FAR struct file *filep)
   DEBUGASSERT(reader != NULL);
 
   nxsem_init(&reader->fifo.rx_sem, 0, 0);
+  reader->rxwatermark = SIZE_MAX;
   filep->f_priv = reader;
 
   return reader;
@@ -489,7 +490,7 @@ static ssize_t can_read(FAR struct file *filep, FAR char *buffer,
               fifo->rx_head = 0;
             }
         }
-      while (fifo->rx_head != fifo->rx_tail);
+      while (fifo->rx_head != fifo->rx_tail && ret < reader->rxwatermark);
 
       if (fifo->rx_head != fifo->rx_tail)
         {
@@ -964,6 +965,22 @@ static int can_ioctl(FAR struct file *filep, int cmd, unsigned long arg)
         }
         break;
 
+      /* Set read watermark */
+
+      case CANIOC_SET_IWATERMARK:
+        {
+          reader->rxwatermark = *(FAR size_t *)arg;
+        }
+        break;
+
+      /* Set read watermark */
+
+      case CANIOC_GET_IWATERMARK:
+        {
+          *(FAR size_t *)arg = reader->rxwatermark;
+        }
+        break;
+
       /* Not a "built-in" ioctl command.. perhaps it is unique to this
        * lower-half, device driver.
        */

include/nuttx/can/can.h

@@ -305,6 +305,29 @@
  *                   is returned with the errno variable set to indicate the
  *                   nature of the error.
  *   Dependencies:   None
+ *
+ * CANIOC_SET_IWATERMARK
+ *   Description:    Set read watermark. This watermark limits number of
+ *                   bytes multiple frames can take in read. The frame is not
+ *                   placed to the provided buffer if it would start after
+ *                   the watermark offset (thus value 0 ensures only one
+ *                   frame to be placed into the buffer). The default valued
+ *                   is SIZE_MAX.
+ *
+ *   Argument:       A pointer to an size_t type with watermark value.
+ *   returned Value: Zero (OK) is returned on success.  Otherwise -1 (ERROR)
+ *                   is returned with the errno variable set to indicate the
+ *                   nature of the error.
+ *   Dependencies:   None
+ *
+ * CANIOC_GET_IWATERMARK
+ *   Description:    Get read watermark.
+ *
+ *   Argument:       A pointer to an size_t type for watermark value.
+ *   returned Value: Zero (OK) is returned on success.  Otherwise -1 (ERROR)
+ *                   is returned with the errno variable set to indicate the
+ *                   nature of the error.
+ *   Dependencies:   None
  */
 
 #define CANIOC_RTR                _CANIOC(1)
@@ -326,9 +349,11 @@
 #define CANIOC_GET_STATE          _CANIOC(17)
 #define CANIOC_SET_TRANSVSTATE    _CANIOC(18)
 #define CANIOC_GET_TRANSVSTATE    _CANIOC(19)
+#define CANIOC_SET_IWATERMARK     _CANIOC(20)
+#define CANIOC_GET_IWATERMARK     _CANIOC(21)
 
 #define CAN_FIRST                 0x0001         /* First common command */
-#define CAN_NCMDS                 19             /* 20 common commands   */
+#define CAN_NCMDS                 21             /* 21 common commands   */
 
 /* User defined ioctl commands are also supported. These will be forwarded
  * by the upper-half CAN driver to the lower-half CAN driver via the
@@ -796,13 +821,15 @@ struct can_ops_s
  *
  *   The elements of 'cd_ops', and 'cd_priv'
  *
- * The common logic will initialize all semaphores.
+ * The common logic will initialize all semaphores and set 'watermark' to
+ * 'SIZE_MAX'.
  */
 
 struct can_reader_s
 {
   struct list_node     list;
   struct can_rxfifo_s  fifo;             /* Describes receive FIFO */
+  size_t rxwatermark;
   FAR struct pollfd   *cd_fds;
 };