Add comments to help differentiate the use of serial buffer flush functions

diff --git a/isp_utils.c b/isp_utils.c
index c5cc4e9..9f37c8e 100644 (file)
--- a/isp_utils.c
+++ b/isp_utils.c
@@ -165,6 +165,13 @@ int isp_serial_write(const char* buf, unsigned int buf_size)
        return count;
 }
 
+/* Empty internal buffer of USB-serial bridge
+ * Some USB-Serial bridge include an internal buffer which must be emptied
+ * before sending the first command in order to be able to read the replies
+ * or the bridge would drop the reply if it's internal buffer is full.
+ * This one has no timeout and should end with EWOULDBLOCK or EAGAIN once the
+ * buffer is empty.
+ */
 void isp_serial_flush_input()
 {
        int nb;
@@ -179,6 +186,10 @@ void isp_serial_flush_input()
        }
 }
 
+/* Empty read buffer between commands
+ * The micor-controller has echo on, so we must read the echoed command
+ * before reading the reply.
+ */
 static char next_read_char = 0;
 void isp_serial_empty_buffer()
 {

diff --git a/isp_utils.h b/isp_utils.h
index 6c488bd..56c2317 100644 (file)
--- a/isp_utils.h
+++ b/isp_utils.h
@@ -45,12 +45,23 @@ void isp_dump(const unsigned char* buf, unsigned int buf_size);
  */
 int isp_serial_open(int baudrate, char* serial_device);
 void isp_serial_close(void);
+
+/* Empty internal buffer of USB-serial bridge
+ * Some USB-Serial bridge include an internal buffer which must be emptied
+ * before sending the first command in order to be able to read the replies
+ * or the bridge would drop the reply if it's internal buffer is full.
+ */
 void isp_serial_flush_input(void);
 
 /* Simple write() wrapper, with trace if enabled */
 int isp_serial_write(const char* buf, unsigned int buf_size);
 
+/* Empty read buffer between commands
+ * The micor-controller has echo on, so we must read the echoed command
+ * before reading the reply.
+ */
 void isp_serial_empty_buffer();
+
 /* Try to read at least "min_read" characters from the serial line.
  * Returns -1 on error, 0 on end of file, or read count otherwise.
  */