Clean up the public functions in userial.c.

Change-Id: I6513296a8c606c49a4cadf196d89573948026e4a

1 files changed, 24 insertions, 62 deletions

diff --git a/hci/include/userial.h b/hci/include/userial.h
index f04111bbf..86984f6f8 100644
--- a/hci/include/userial.h
+++ b/hci/include/userial.h
@@ -16,13 +16,8 @@
  *
  ******************************************************************************/
 
-/******************************************************************************
- *
- *  Filename:      userial.h
- *
- *  Description:   Contains definitions used for serial port controls
- *
- ******************************************************************************/
+// This module manages the serial port over which HCI commands
+// and data are sent/received.
 
 #pragma once
 
@@ -50,67 +45,34 @@ typedef enum {
   USERIAL_PORT_18,
 } userial_port_t;
 
-typedef enum {
-    USERIAL_OP_RXFLOW_ON,
-    USERIAL_OP_RXFLOW_OFF,
-} userial_ioctl_op_t;
-
-/*******************************************************************************
-**
-** Function        userial_init
-**
-** Description     Initializes the userial driver
-**
-*******************************************************************************/
+// Initializes the userial module. This function should only ever be called once.
+// It returns true if the module could be initialized, false if there was an error.
 bool userial_init(void);
 
-/*******************************************************************************
-**
-** Function        userial_open
-**
-** Description     Open Bluetooth device with the port ID
-**
-*******************************************************************************/
+// Opens the given serial port. Returns true if successful, false otherwise.
+// Once this function is called, the userial module will begin producing
+// buffers from data read off the serial port. If you wish to pause the
+// production of buffers, call |userial_pause_reading|. You can then resume
+// by calling |userial_resume_reading|. This function returns true if the
+// serial port was successfully opened and buffer production has started. It
+// returns false if there was an error.
 bool userial_open(userial_port_t port);
+void userial_close(void);
 
-/*******************************************************************************
-**
-** Function        userial_read
-**
-** Description     Read data from the userial port
-**
-** Returns         Number of bytes actually read from the userial port and
-**                 copied into p_data.  This may be less than len.
-**
-*******************************************************************************/
+// Reads a maximum of |len| bytes from the serial port into |p_buffer|.
+// This function returns the number of bytes actually read, which may be
+// less than |len|. This function will not block.
 uint16_t userial_read(uint16_t msg_id, uint8_t *p_buffer, uint16_t len);
 
-/*******************************************************************************
-**
-** Function        userial_write
-**
-** Description     Write data to the userial port
-**
-** Returns         Number of bytes actually written to the userial port. This
-**                 may be less than len.
-**
-*******************************************************************************/
+// Writes a maximum of |len| bytes from |p_data| to the serial port.
+// This function returns the number of bytes actually written, which may be
+// less than |len|. This function may block.
 uint16_t userial_write(uint16_t msg_id, const uint8_t *p_data, uint16_t len);
 
-/*******************************************************************************
-**
-** Function        userial_close
-**
-** Description     Close the userial port
-**
-*******************************************************************************/
-void userial_close(void);
+// Pauses reading data from the serial port. No new buffers will be produced
+// until |userial_resume_reading| is called. This function is idempotent.
+void userial_pause_reading(void);
 
-/*******************************************************************************
-**
-** Function        userial_ioctl
-**
-** Description     ioctl inteface
-**
-*******************************************************************************/
-void userial_ioctl(userial_ioctl_op_t op);
+// Resumes reading data from the serial port if reads were previously paused.
+// This function is idempotent.
+void userial_resume_reading(void);