Revise BT vendor lib interface (1/2)

1. Move UART port configuration into vendor lib to respect the fact that each
   vendor might have different UART port settings for its own chipsets.

2. Detail bt_vendor_lib.h header file with usage instructions.

Change-Id: I10dc44afd9b3cc1985769166a717089728281296

2 files changed, 181 insertions, 65 deletions

diff --git a/hci/include/bt_vendor_lib.h b/hci/include/bt_vendor_lib.h
index 867ca68..462d4e6 100644
--- a/hci/include/bt_vendor_lib.h
+++ b/hci/include/bt_vendor_lib.h
@@ -57,16 +57,109 @@
 
 /** Typedefs and defines */
 
-/** Vendor operations */
+/** Vendor specific operations OPCODE */
 typedef enum {
+/*  [operation]
+ *      Power on or off the BT Controller.
+ *  [input param]
+ *      A pointer to int type with content of bt_vendor_power_state_t.
+ *      Typecasting conversion: (int *) param.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      None.
+ */
     BT_VND_OP_POWER_CTRL,
+
+/*  [operation]
+ *      Perform any vendor specific initialization or configuration
+ *      on the BT Controller. This is called before stack initialization.
+ *  [input param]
+ *      None.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      Must call fwcfg_cb to notify the stack of the completion of vendor
+ *      specific initialization once it has been done.
+ */
     BT_VND_OP_FW_CFG,
+
+/*  [operation]
+ *      Perform any vendor specific SCO/PCM configuration on the BT Controller.
+ *      This is called after stack initialization.
+ *  [input param]
+ *      None.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      Must call scocfg_cb to notify the stack of the completion of vendor
+ *      specific SCO configuration once it has been done.
+ */
     BT_VND_OP_SCO_CFG,
+
+/*  [operation]
+ *      Open UART port on where the BT Controller is attached.
+ *      This is called before stack initialization.
+ *  [input param]
+ *      None.
+ *  [return]
+ *      fd - the file descriptor of UART port for Bluetooth.
+ *  [callback]
+ *      None.
+ */
     BT_VND_OP_USERIAL_OPEN,
+
+/*  [operation]
+ *      Close the previously opened UART port.
+ *  [input param]
+ *      None.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      None.
+ */
     BT_VND_OP_USERIAL_CLOSE,
-    BT_VND_OP_USERIAL_SET_BAUD,
+
+/*  [operation]
+ *      Get the LPM idle timeout in milliseconds.
+ *      The stack uses this information to launch a timer delay before it
+ *      attempts to de-assert LPM WAKE signal once downstream HCI packet
+ *      has been delivered.
+ *  [input param]
+ *      A pointer to uint32_t type which is passed in by the stack. And, it
+ *      requires the vendor lib to fill up the content before returning
+ *      the call.
+ *      Typecasting conversion: (uint32_t *) param.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      None.
+ */
     BT_VND_OP_GET_LPM_IDLE_TIMEOUT,
+
+/*  [operation]
+ *      Enable or disable LPM mode on BT Controller.
+ *  [input param]
+ *      A pointer to uint8_t type with content of bt_vendor_lpm_mode_t.
+ *      Typecasting conversion: (uint8_t *) param.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      Must call lpm_cb to notify the stack of the completion of LPM
+ *      disable/enable process once it has been done.
+ */
     BT_VND_OP_LPM_SET_MODE,
+
+/*  [operation]
+ *      Assert or Deassert LPM WAKE on BT Controller.
+ *  [input param]
+ *      A pointer to uint8_t type with content of bt_vendor_lpm_wake_state_t.
+ *      Typecasting conversion: (uint8_t *) param.
+ *  [return]
+ *      0 - default, don't care.
+ *  [callback]
+ *      None.
+ */
     BT_VND_OP_LPM_WAKE_SET_STATE,
 } bt_vendor_opcode_t;
 
@@ -76,13 +169,19 @@ typedef enum {
     BT_VND_PWR_ON,
 }  bt_vendor_power_state_t;
 
+/** LPM disable/enable request */
+typedef enum {
+    BT_VND_LPM_DISABLE,
+    BT_VND_LPM_ENABLE,
+} bt_vendor_lpm_mode_t;
+
 /** LPM WAKE set state request */
 typedef enum {
     BT_VND_LPM_WAKE_ASSERT,
     BT_VND_LPM_WAKE_DEASSERT,
 } bt_vendor_lpm_wake_state_t;
 
-/** Result of vendor operations */
+/** Callback result values */
 typedef enum {
     BT_VND_OP_RESULT_SUCCESS,
     BT_VND_OP_RESULT_FAIL,
@@ -95,22 +194,83 @@ typedef enum {
 /* vendor initialization/configuration callback */
 typedef void (*cfg_result_cb)(bt_vendor_op_result_t result);
 
-/* datapath buffer allocation callback (callout) */
+/* datapath buffer allocation callback (callout)
+ *
+ *  Vendor lib needs to request a buffer through the alloc callout function
+ *  from HCI lib if the buffer is for constructing a HCI Command packet which
+ *  will be sent through xmit_cb to BT Controller.
+ *
+ *  For each buffer allocation, the requested size needs to be big enough to
+ *  accommodate the below header plus a complete HCI packet --
+ *      typedef struct
+ *      {
+ *          uint16_t          event;
+ *          uint16_t          len;
+ *          uint16_t          offset;
+ *          uint16_t          layer_specific;
+ *      } HC_BT_HDR;
+ *
+ *  HCI lib returns a pointer to the buffer where Vendor lib should use to
+ *  construct a HCI command packet as below format:
+ *
+ *  --------------------------------------------
+ *  |  HC_BT_HDR  |  HCI command               |
+ *  --------------------------------------------
+ *  where
+ *      HC_BT_HDR.event = 0x2000;
+ *      HC_BT_HDR.len = Length of HCI command;
+ *      HC_BT_HDR.offset = 0;
+ *      HC_BT_HDR.layer_specific = 0;
+ *
+ *  For example, a HCI_RESET Command will be formed as
+ *  ------------------------
+ *  |  HC_BT_HDR  |03|0c|00|
+ *  ------------------------
+ *  with
+ *      HC_BT_HDR.event = 0x2000;
+ *      HC_BT_HDR.len = 3;
+ *      HC_BT_HDR.offset = 0;
+ *      HC_BT_HDR.layer_specific = 0;
+ */
 typedef void* (*malloc_cb)(int size);
 
 /* datapath buffer deallocation callback (callout) */
 typedef void (*mdealloc_cb)(void *p_buf);
 
-/* define callback of the cmd_xmit_cb */
+/* define callback of the cmd_xmit_cb
+ *
+ *  The callback function which HCI lib will call with the return of command
+ *  complete packet. Vendor lib is responsible for releasing the buffer passed
+ *  in at the p_mem parameter by calling dealloc callout function.
+ */
 typedef void (*tINT_CMD_CBACK)(void *p_mem);
 
-/* hci command packet transmit callback (callout) */
+/* hci command packet transmit callback (callout)
+ *
+ *  Vendor lib calls xmit_cb callout function in order to send a HCI Command
+ *  packet to BT Controller. The buffer carrying HCI Command packet content
+ *  needs to be first allocated through the alloc callout function.
+ *  HCI lib will release the buffer for Vendor lib once it has delivered the
+ *  packet content to BT Controller.
+ *
+ *  Vendor lib needs also provide a callback function (p_cback) which HCI lib
+ *  will call with the return of command complete packet.
+ *
+ *  The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of
+ *  HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command
+ *  packet.
+ */
 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback);
 
 typedef struct {
     /** set to sizeof(bt_vendor_callbacks_t) */
     size_t         size;
 
+    /*
+     * Callback and callout functions have implemented in HCI libray
+     * (libbt-hci.so).
+     */
+
     /* notifies caller result of firmware configuration request */
     cfg_result_cb  fwcfg_cb;
 
@@ -137,8 +297,12 @@ typedef struct {
     /** Set to sizeof(bt_vndor_interface_t) */
     size_t          size;
 
+    /*
+     * Functions need to be implemented in Vendor libray (libbt-vendor.so).
+     */
+
     /**
-     * Opens the interface and provides the callback routines
+     * Caller will open the interface and pass in the callback routines
      * to the implemenation of this interface.
      */
     int   (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char *local_bdaddr);
@@ -152,10 +316,16 @@ typedef struct {
 
 
 /*
- * External shared lib functions
+ * External shared lib functions/data
  */
 
-extern const bt_vendor_interface_t* bt_vendor_get_interface(void);
+/* Entry point of DLib --
+ *      Vendor library needs to implement the body of bt_vendor_interface_t
+ *      structure and uses the below name as the variable name. HCI library
+ *      will use this symbol name to get address of the object through the
+ *      dlsym call.
+ */
+extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE;
 
 #endif /* BT_VENDOR_LIB_H */
 
diff --git a/hci/include/userial.h b/hci/include/userial.h
index db3a8cf..92458e5 100644
--- a/hci/include/userial.h
+++ b/hci/include/userial.h
@@ -80,42 +80,6 @@
 #define USERIAL_PORT_17         16
 #define USERIAL_PORT_18         17
 
-/**** baud rates ****/
-#define USERIAL_BAUD_300        0
-#define USERIAL_BAUD_600        1
-#define USERIAL_BAUD_1200       2
-#define USERIAL_BAUD_2400       3
-#define USERIAL_BAUD_9600       4
-#define USERIAL_BAUD_19200      5
-#define USERIAL_BAUD_57600      6
-#define USERIAL_BAUD_115200     7
-#define USERIAL_BAUD_230400     8
-#define USERIAL_BAUD_460800     9
-#define USERIAL_BAUD_921600     10
-#define USERIAL_BAUD_1M         11
-#define USERIAL_BAUD_1_5M       12
-#define USERIAL_BAUD_2M         13
-#define USERIAL_BAUD_3M         14
-#define USERIAL_BAUD_4M         15
-#define USERIAL_BAUD_AUTO       16
-
-/**** Data Format ****/
-/* Stop Bits */
-#define USERIAL_STOPBITS_1      1
-#define USERIAL_STOPBITS_1_5    (1<<1)
-#define USERIAL_STOPBITS_2      (1<<2)
-
-/* Parity Bits */
-#define USERIAL_PARITY_NONE     (1<<3)
-#define USERIAL_PARITY_EVEN     (1<<4)
-#define USERIAL_PARITY_ODD      (1<<5)
-
-/* Data Bits */
-#define USERIAL_DATABITS_5      (1<<6)
-#define USERIAL_DATABITS_6      (1<<7)
-#define USERIAL_DATABITS_7      (1<<8)
-#define USERIAL_DATABITS_8      (1<<9)
-
 typedef enum {
     USERIAL_OP_INIT,
     USERIAL_OP_RXFLOW_ON,
@@ -126,13 +90,6 @@ typedef enum {
 **  Type definitions
 ******************************************************************************/
 
-/* Structure used to configure serial port during open */
-typedef struct
-{
-    uint16_t fmt;       /* Data format */
-    uint8_t  baud;      /* Baud rate */
-} tUSERIAL_CFG;
-
 /******************************************************************************
 **  Extern variables and functions
 ******************************************************************************/
@@ -156,12 +113,12 @@ uint8_t userial_init(void);
 **
 ** Function        userial_open
 **
-** Description     Open the indicated serial port with the given configuration
+** Description     Open Bluetooth device with the port ID
 **
 ** Returns         TRUE/FALSE
 **
 *******************************************************************************/
-uint8_t userial_open(uint8_t port, tUSERIAL_CFG *p_cfg);
+uint8_t userial_open(uint8_t port);
 
 /*******************************************************************************
 **
@@ -200,17 +157,6 @@ void userial_close(void);
 
 /*******************************************************************************
 **
-** Function        userial_change_baud
-**
-** Description     Change baud rate of userial port
-**
-** Returns         None
-**
-*******************************************************************************/
-void userial_change_baud(uint8_t baud);
-
-/*******************************************************************************
-**
 ** Function        userial_ioctl
 **
 ** Description     ioctl inteface