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

6 files changed, 202 insertions, 103 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 
diff --git a/hci/src/bt_hci_bdroid.c b/hci/src/bt_hci_bdroid.c
index 85199ec..91a80e7 100644
--- a/hci/src/bt_hci_bdroid.c
+++ b/hci/src/bt_hci_bdroid.c
@@ -122,12 +122,6 @@ static volatile uint8_t lib_running = 0;
 static volatile uint16_t ready_events = 0;
 static volatile uint8_t tx_cmd_pkts_pending = FALSE;
 
-static const tUSERIAL_CFG userial_init_cfg =
-{
-    (USERIAL_DATABITS_8 | USERIAL_PARITY_NONE | USERIAL_STOPBITS_1),
-    USERIAL_BAUD_115200
-};
-
 /******************************************************************************
 **  Functions
 ******************************************************************************/
@@ -398,7 +392,7 @@ static void *bt_hc_worker_thread(void *arg)
 
         if (events & HC_EVENT_PRELOAD)
         {
-            userial_open(USERIAL_PORT_1, (tUSERIAL_CFG *) &userial_init_cfg);
+            userial_open(USERIAL_PORT_1);
 
             /* Calling vendor-specific part */
             if (bt_vnd_if)
diff --git a/hci/src/hci_h4.c b/hci/src/hci_h4.c
index b10d173..36c692a 100644
--- a/hci/src/hci_h4.c
+++ b/hci/src/hci_h4.c
@@ -304,7 +304,20 @@ uint8_t internal_event_intercept(void)
                 HCIH4DBG( \
                 "Intercept CommandCompleteEvent for internal command (0x%04X)",\
                           opcode);
-                p_cb->int_cmd[p_cb->int_cmd_rd_idx].cback(p_cb->p_rcv_msg);
+                if (p_cb->int_cmd[p_cb->int_cmd_rd_idx].cback != NULL)
+                {
+                    p_cb->int_cmd[p_cb->int_cmd_rd_idx].cback(p_cb->p_rcv_msg);
+                }
+                else
+                {
+                    // Missing cback function!
+                    // Release the p_rcv_msg buffer.
+                    if (bt_hc_cbacks)
+                    {
+                        bt_hc_cbacks->dealloc((TRANSAC) p_cb->p_rcv_msg, \
+                                              (char *) (p_cb->p_rcv_msg + 1));
+                    }
+                }
                 p_cb->int_cmd_rd_idx = ((p_cb->int_cmd_rd_idx+1) & \
                                         INT_CMD_PKT_IDX_MASK);
                 p_cb->int_cmd_rsp_pending--;
diff --git a/hci/src/lpm.c b/hci/src/lpm.c
index 74d0809..78ee7dc 100644
--- a/hci/src/lpm.c
+++ b/hci/src/lpm.c
@@ -336,8 +336,9 @@ void lpm_enable(uint8_t turn_on)
     /* Calling vendor-specific part */
     if (bt_vnd_if)
     {
+        uint8_t lpm_cmd = (turn_on) ? BT_VND_LPM_ENABLE : BT_VND_LPM_DISABLE;
         bt_lpm_cb.state = (turn_on) ? LPM_ENABLING : LPM_DISABLING;
-        bt_vnd_if->op(BT_VND_OP_LPM_SET_MODE, &turn_on);
+        bt_vnd_if->op(BT_VND_OP_LPM_SET_MODE, &lpm_cmd);
     }
 }
 
diff --git a/hci/src/userial.c b/hci/src/userial.c
index 92540c9..0b37c3f 100644
--- a/hci/src/userial.c
+++ b/hci/src/userial.c
@@ -104,7 +104,6 @@ typedef struct
     int             sock;
     uint8_t         port;
     pthread_t       read_thread;
-    tUSERIAL_CFG    cfg;
     BUFFER_Q        rx_q;
     HC_BT_HDR      *p_rx_hdr;
 } tUSERIAL_CB;
@@ -326,18 +325,18 @@ 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)
 {
     struct sched_param param;
     int policy, result;
     pthread_attr_t thread_attr;
 
-    USERIALDBG("userial_open(port:%d, baud:%d)", port, p_cfg->baud);
+    USERIALDBG("userial_open(port:%d)", port);
 
     if (userial_running)
     {
@@ -355,7 +354,7 @@ uint8_t userial_open(uint8_t port, tUSERIAL_CFG *p_cfg)
     /* Calling vendor-specific part */
     if (bt_vnd_if)
     {
-        userial_cb.sock = bt_vnd_if->op(BT_VND_OP_USERIAL_OPEN, p_cfg);
+        userial_cb.sock = bt_vnd_if->op(BT_VND_OP_USERIAL_OPEN, NULL);
     }
     else
     {
@@ -373,7 +372,6 @@ uint8_t userial_open(uint8_t port, tUSERIAL_CFG *p_cfg)
     USERIALDBG( "sock = %d", userial_cb.sock);
 
     userial_cb.port = port;
-    memcpy(&userial_cb.cfg, p_cfg, sizeof(tUSERIAL_CFG));
 
     pthread_attr_init(&thread_attr);
 
@@ -521,29 +519,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)
-{
-    /* Calling vendor-specific part */
-    if (bt_vnd_if)
-    {
-        bt_vnd_if->op(BT_VND_OP_USERIAL_SET_BAUD, &baud);
-    }
-    else
-    {
-        ALOGE("userial_change_baud: missing vendor lib interface !!!");
-        ALOGE("userial_change_baud: unable to change UART baud rate");
-    }
-}
-
-/*******************************************************************************
-**
 ** Function        userial_ioctl
 **
 ** Description     ioctl inteface