path: root/hci/include/bt_vendor_lib.h

/******************************************************************************
 *
 *  Copyright (C) 2009-2012 Broadcom Corporation
 *
 *  This program is the proprietary software of Broadcom Corporation and/or its
 *  licensors, and may only be used, duplicated, modified or distributed
 *  pursuant to the terms and conditions of a separate, written license
 *  agreement executed between you and Broadcom (an "Authorized License").
 *  Except as set forth in an Authorized License, Broadcom grants no license
 *  (express or implied), right to use, or waiver of any kind with respect to
 *  the Software, and Broadcom expressly reserves all rights in and to the
 *  Software and all intellectual property rights therein.
 *  IF YOU HAVE NO AUTHORIZED LICENSE, THEN YOU HAVE NO RIGHT TO USE THIS
 *  SOFTWARE IN ANY WAY, AND SHOULD IMMEDIATELY NOTIFY BROADCOM AND DISCONTINUE
 *  ALL USE OF THE SOFTWARE.
 *
 *  Except as expressly set forth in the Authorized License,
 *
 *  1.     This program, including its structure, sequence and organization,
 *         constitutes the valuable trade secrets of Broadcom, and you shall
 *         use all reasonable efforts to protect the confidentiality thereof,
 *         and to use this information only in connection with your use of
 *         Broadcom integrated circuit products.
 *
 *  2.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED
 *         "AS IS" AND WITH ALL FAULTS AND BROADCOM MAKES NO PROMISES,
 *         REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY,
 *         OR OTHERWISE, WITH RESPECT TO THE SOFTWARE.  BROADCOM SPECIFICALLY
 *         DISCLAIMS ANY AND ALL IMPLIED WARRANTIES OF TITLE, MERCHANTABILITY,
 *         NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, LACK OF VIRUSES,
 *         ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR
 *         CORRESPONDENCE TO DESCRIPTION. YOU ASSUME THE ENTIRE RISK ARISING OUT
 *         OF USE OR PERFORMANCE OF THE SOFTWARE.
 *
 *  3.     TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL BROADCOM OR
 *         ITS LICENSORS BE LIABLE FOR
 *         (i)   CONSEQUENTIAL, INCIDENTAL, SPECIAL, INDIRECT, OR EXEMPLARY
 *               DAMAGES WHATSOEVER ARISING OUT OF OR IN ANY WAY RELATING TO
 *               YOUR USE OF OR INABILITY TO USE THE SOFTWARE EVEN IF BROADCOM
 *               HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES; OR
 *         (ii)  ANY AMOUNT IN EXCESS OF THE AMOUNT ACTUALLY PAID FOR THE
 *               SOFTWARE ITSELF OR U.S. $1, WHICHEVER IS GREATER. THESE
 *               LIMITATIONS SHALL APPLY NOTWITHSTANDING ANY FAILURE OF
 *               ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.
 *
 ******************************************************************************/

#ifndef BT_VENDOR_LIB_H
#define BT_VENDOR_LIB_H

#include <stdint.h>
#include <sys/cdefs.h>
#include <sys/types.h>

/** Struct types */


/** Typedefs and defines */

/** 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]
 *      A pointer to int array type for open file descriptors.
 *      The mapping of HCI channel to fd slot in the int array is given in
 *      bt_vendor_hci_channels_t.
 *      And, it requires the vendor lib to fill up the content before returning
 *      the call.
 *      Typecasting conversion: (int (*)[]) param.
 *  [return]
 *      Numbers of opened file descriptors.
     *      Valid number:
     *          1 - CMD/EVT/ACL-In/ACL-Out via the same fd (e.g. UART)
     *          2 - CMD/EVT on one fd, and ACL-In/ACL-Out on the other fd
     *          4 - CMD, EVT, ACL-In, ACL-Out are on their individual fd
 *  [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,

/*  [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;

/** Power on/off control states */
typedef enum {
    BT_VND_PWR_OFF,
    BT_VND_PWR_ON,
}  bt_vendor_power_state_t;

/** Define HCI channel identifier in the file descriptors array
    used in BT_VND_OP_USERIAL_OPEN operation.
 */
typedef enum {
    CH_CMD,     // HCI Command channel
    CH_EVT,     // HCI Event channel
    CH_ACL_OUT, // HCI ACL downstream channel
    CH_ACL_IN,  // HCI ACL upstream channel

    CH_MAX      // Total channels
}  bt_vendor_hci_channels_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;

/** Callback result values */
typedef enum {
    BT_VND_OP_RESULT_SUCCESS,
    BT_VND_OP_RESULT_FAIL,
} bt_vendor_op_result_t;

/*
 * Bluetooth Host/Controller Vendor callback structure.
 */

/* vendor initialization/configuration callback */
typedef void (*cfg_result_cb)(bt_vendor_op_result_t result);

/* 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
 *
 *  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)
 *
 *  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;

    /* notifies caller result of sco configuration request */
    cfg_result_cb  scocfg_cb;

    /* notifies caller result of lpm enable/disable */
    cfg_result_cb  lpm_cb;

    /* buffer allocation request */
    malloc_cb   alloc;

    /* buffer deallocation request */
    mdealloc_cb dealloc;

    /* hci command packet transmit request */
    cmd_xmit_cb xmit_cb;
} bt_vendor_callbacks_t;

/*
 * Bluetooth Host/Controller VENDOR Interface
 */
typedef struct {
    /** Set to sizeof(bt_vndor_interface_t) */
    size_t          size;

    /*
     * Functions need to be implemented in Vendor libray (libbt-vendor.so).
     */

    /**
     * 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);

    /**  Vendor specific operations */
    int (*op)(bt_vendor_opcode_t opcode, void *param);

    /** Closes the interface */
    void  (*cleanup)(void);
} bt_vendor_interface_t;


/*
 * External shared lib functions/data
 */

/* 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 */