1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <cstdint> 20 21 #include "module.h" 22 23 namespace bluetooth::hal { 24 25 enum SocketStatus { 26 SUCCESS = 0, 27 FAILURE, 28 }; 29 30 struct EndpointInfo { 31 // The ID of the Hub to which the end point belongs for hardware offload data path. 32 uint64_t hub_id; 33 34 // The ID of the Hub endpoint for hardware offload data path. 35 uint64_t endpoint_id; 36 }; 37 38 struct LeCocCapabilities { 39 // Maximum number of LE COC sockets supported. If not supported, the value must be zero. 40 int number_of_supported_sockets; 41 42 // Local Maximum Transmission Unit size in octets. 43 uint16_t mtu; 44 }; 45 46 struct RfcommCapabilities { 47 // Maximum number of RFCOMM sockets supported. If not supported, the value must be zero. 48 int number_of_supported_sockets; 49 50 // Maximum frame size in octets negotiated during DLCI establishment. 51 uint16_t max_frame_size; 52 }; 53 54 struct SocketCapabilities { 55 LeCocCapabilities le_coc_capabilities; 56 RfcommCapabilities rfcomm_capabilities; 57 }; 58 59 struct LeCocChannelInfo { 60 // L2cap local channel ID. 61 uint16_t local_cid; 62 63 // L2cap remote channel ID. 64 uint16_t remote_cid; 65 66 // PSM for L2CAP LE CoC. 67 uint16_t psm; 68 69 // Local Maximum Transmission Unit for LE COC specifying the maximum SDU size in bytes that the 70 // local L2CAP layer can receive. 71 uint16_t local_mtu; 72 73 // Remote Maximum Transmission Unit for LE COC specifying the maximum SDU size in bytes that the 74 // remote L2CAP layer can receive. 75 uint16_t remote_mtu; 76 77 // Local Maximum PDU payload Size in bytes that the local L2CAP layer can receive. 78 uint16_t local_mps; 79 80 // Remote Maximum PDU payload Size in bytes that the remote L2CAP layer can receive. 81 uint16_t remote_mps; 82 83 // Protocol initial credits at Rx path. 84 uint16_t initial_rx_credits; 85 86 // Protocol initial credits at Tx path. 87 uint16_t initial_tx_credits; 88 }; 89 90 struct RfcommChannelInfo { 91 // L2cap local channel ID for RFCOMM. 92 int local_cid; 93 94 // L2cap remote channel ID for RFCOMM. 95 int remote_cid; 96 97 // Local Maximum Transmission Unit Size in bytes that the local L2CAP layer can receive. 98 int local_mtu; 99 100 // Remote Maximum Transmission Unit Size in bytes that the remote L2CAP layer can receive. 101 int remote_mtu; 102 103 // Protocol initial credits at Rx path. 104 int initial_rx_credits; 105 106 // Protocol initial credits at Tx path. 107 int initial_tx_credits; 108 109 // Data Link Connection Identifier (DLCI). 110 int dlci; 111 112 // Maximum frame size negotiated during DLCI establishment. 113 int max_frame_size; 114 115 // Flag of whether the Android stack initiated the RFCOMM multiplexer control channel. 116 bool mux_initiator; 117 }; 118 119 struct SocketContext { 120 // Identifier assigned to the socket by the host stack when the socket is connected. 121 uint64_t socket_id; 122 123 // Descriptive socket name provided by the host app when it created this socket. 124 std::string name; 125 126 // ACL connection handle for the socket. 127 uint16_t acl_connection_handle; 128 129 // Channel information of different protocol used for the socket. 130 std::variant<LeCocChannelInfo, RfcommChannelInfo> channel_info; 131 132 // Endpoint information. 133 EndpointInfo endpoint_info; 134 }; 135 136 /** 137 * SocketHalCallback provides an interface for receiving asynchronous events from socket HAL. 138 * Implementations of this class can be registered with the stack to receive these callbacks. 139 * 140 * Callback methods in this interface are invoked from the binder thread. This means that 141 * implementations must be thread-safe and handle any necessary synchronization to avoid race 142 * conditions or other concurrency issues. The callee is solely responsible for ensuring thread 143 * safety within the callback methods. 144 */ 145 class SocketHalCallback { 146 public: 147 virtual ~SocketHalCallback() = default; 148 149 /** 150 * Invoked when IBluetoothSocket.opened() has been completed. 151 * 152 * @param socket_id Identifier assigned to the socket by the host stack 153 * @param status Status indicating success or failure 154 */ 155 virtual void SocketOpenedComplete(uint64_t socket_id, SocketStatus status) const = 0; 156 157 /** 158 * Invoked when offload app or stack requests host stack to close the socket. 159 * 160 * @param socket_id Identifier assigned to the socket by the host stack 161 */ 162 virtual void SocketClose(uint64_t socket_id) const = 0; 163 }; 164 165 /** 166 * SocketHal provides an interface to low-power processors, enabling Bluetooth Offload Socket 167 * functionality. 168 * 169 * Bluetooth Offload Socket allows the transfer of channel information from an established 170 * BluetoothSocket to a low-power processor. This enables the offload stack on the low-power 171 * processor to handle packet reception, processing, and transmission independently. This offloading 172 * process prevents the need to wake the main application processor, improving power efficiency. 173 */ 174 class SocketHal : public ::bluetooth::Module { 175 public: 176 static const ModuleFactory Factory; 177 178 virtual ~SocketHal() = default; 179 180 /** 181 * Registers a socket hal callback function to receive asynchronous events from socket HAL. 182 * 183 * @param callback A pointer to the callback function. Must not be nullptr and must have static 184 * lifetime. 185 * @return True if the callback was successfully registered, false otherwise. 186 */ 187 virtual bool RegisterCallback(hal::SocketHalCallback const* callback) = 0; 188 189 /** 190 * Retrieves the supported offloaded socket capabilities. 191 * 192 * @return Supported socket capabilities 193 */ 194 virtual hal::SocketCapabilities GetSocketCapabilities() const = 0; 195 196 /** 197 * Notifies the socket HAL that the socket has been opened. 198 * 199 * @param context Socket context including socket ID, channel, hub, and endpoint info 200 * @return Result of calling this method 201 */ 202 virtual bool Opened(const hal::SocketContext& context) const = 0; 203 204 /** 205 * Notifies the socket HAL that the socket has been closed. 206 * 207 * @param socket_id Identifier assigned to the socket by the host stack 208 */ 209 virtual void Closed(uint64_t socket_id) const = 0; 210 }; 211 212 } // namespace bluetooth::hal 213