diff options
author | Lucas Abel <22837557+uael@users.noreply.github.com> | 2023-09-26 15:30:05 +0000 |
---|---|---|
committer | Lucas Abel <22837557+uael@users.noreply.github.com> | 2023-09-27 19:29:09 +0200 |
commit | e378db8fafb18eae0a8d88e9038a65167de5e5f5 (patch) | |
tree | 83afca499fbac3c69a5e1c0474a0879f25c713d1 | |
parent | 47835e11a701bfdb0bffee319e31869b88032a1a (diff) | |
download | bt-test-interfaces-e378db8fafb18eae0a8d88e9038a65167de5e5f5.tar.gz |
l2cap: add documentation
-rw-r--r-- | pandora/l2cap.proto | 90 |
1 files changed, 72 insertions, 18 deletions
diff --git a/pandora/l2cap.proto b/pandora/l2cap.proto index 79332c4..055f893 100644 --- a/pandora/l2cap.proto +++ b/pandora/l2cap.proto @@ -22,86 +22,126 @@ import "pandora/host.proto"; option java_outer_classname = "L2CAPProto"; +// L2CAP (Logical Link Control and Adaptation Protocol) services for managing channels +// and data communication over ACL connections. This protocol is essential for +// creating multiplexed data channels over the underlying ACL connections in Bluetooth. service L2CAP { // Establish an L2CAP channel on an ACL connection. rpc Connect(ConnectRequest) returns (ConnectResponse); - // Wait and accept incoming L2CAP channels on an ACL connection. + // Await and accept incoming L2CAP channels on an existing ACL connection. + // Returns a stream of channel, this accept and yield channels until the stream + // is closed. Every incoming L2CAP channel connection request not handled by this + // method should be rejected. rpc OnConnection(OnConnectionRequest) returns (stream OnConnectionResponse); - // Disconnect an L2CAP channel. + // Disconnect an established L2CAP channel. rpc Disconnect(DisconnectRequest) returns (DisconnectResponse); - // Wait an L2CAP channel to be disconnected. - rpc WaitDisconnection(WaitDisconnectionRequest) - returns (WaitDisconnectionResponse); - // Receive data from an L2CAP channel. + // Await an established L2CAP channel's termination. + rpc WaitDisconnection(WaitDisconnectionRequest) returns (WaitDisconnectionResponse); + // Fetch data received from an active L2CAP channel. + // Packets are yielded until the stream is closed, packets are droped otherwise. rpc Receive(ReceiveRequest) returns (stream ReceiveResponse); - // Send data to an L2CAP channel. + // Send data over an L2CAP channel to a connected device. rpc Send(SendRequest) returns (SendResponse); } +// Potential reasons for command rejections in the L2CAP protocol. enum CommandRejectReason { + // The command wasn't understood by the receiver. COMMAND_NOT_UNDERSTOOD = 0; + // The received signal exceeds the allowed MTU (Maximum Transmission Unit). SIGNAL_MTU_EXCEEDED = 1; + // The received command includes an invalid Channel Identifier (CID). INVALID_CID_IN_REQUEST = 2; } +// A Token representing a unique L2CAP channel for data communication. message Channel { + // Opaque value filled by the gRPC server, must not be modified nor crafted. google.protobuf.Any cookie = 1; } +// Request for establishing an L2CAP connection-oriented channel, +// where data is transmitted with acknowledgment. message ConnectionOrientedChannelRequest { - // Protocol/Service Multiplexer. + // Protocol/Service Multiplexer (PSM) for identifying the upper-layer protocol. uint32 psm = 1; - // Maximum transmission unit. + // Defines the maximum size of data payload (in bytes) that can be sent in a single packet. uint32 mtu = 2; } +// Request for establishing a credit-based L2CAP channel, +// typically used in BLE (Bluetooth Low Energy) when precise flow control is required. message CreditBasedChannelRequest { - // Simplified Protocol/Service Multiplexer. + // Simplified Protocol/Service Multiplexer (sPSM) for identifying the upper-layer protocol in BLE. uint32 spsm = 1; - // Maximum transmission unit. + // Defines the maximum size of data payload (in bytes) that can be sent in a single packet. uint32 mtu = 2; - // Maximum PDU payload size. + // Maximum size of the PDU (Protocol Data Unit) payload. uint32 mps = 3; - // Maximum number of packets to transmit. + // Initial credits given for flow control, defining the number of PDUs the sender can transmit. uint32 initial_credit = 4; } +// Request for establishing a fixed L2CAP channel, often pre-defined for specific purposes. message FixedChannelRequest { - // Fixed channel identifier + // Fixed Channel Identifier (CID). Represents the unique identifier for the fixed channel. + // Available CIDs are: + // - 0x0001: L2CAP Signaling Channel + // - 0x0002: Connectionless Channel + // - 0x0003: AMP Manager Protocol + // - 0x0004: Attribute Protocol (ATT) for BLE + // - 0x0005: L2CAP Signaling Channel for BLE + // - 0x0006: Security Manager Protocol for BLE + // - 0x0007: Security Manager Protocol for BR/EDR + // - CIDs in the range of 0x0007 to 0x003F are reserved for standardization purposes. uint32 cid = 1; } +// Request of the `Connect` method. message ConnectRequest { - // BR/EDR or Low-Energy connection. + // Specifies the underlying ACL connection, either BR/EDR (Basic Rate/Enhanced Data Rate) or BLE. Connection connection = 1; + // Defines the type and specifics of the channel to establish. oneof type { + // Request a fixed channel. FixedChannelRequest fixed = 2; + // Request a connection-oriented channel. ConnectionOrientedChannelRequest basic = 3; + // Request a BLE credit-based channel. CreditBasedChannelRequest le_credit_based = 4; + // Request an enhanced credit-based channel. CreditBasedChannelRequest enhanced_credit_based = 5; } } +// Response of the `Connect` method. message ConnectResponse { oneof result { + // Error details if the connection failed. CommandRejectReason error = 1; + // Details of the established channel on success. Channel channel = 2; } } +// Request of the `OnConnection` method. message OnConnectionRequest { - // BR/EDR or Low-Energy connection. - // Note: On some platforms, directional server might not be applicable, so - // connections on other ACL connections will also be accepted but not reported + // Specifies the underlying ACL connection, either BR/EDR or BLE. Connection connection = 1; + // Defines the type and specifics of the channel to wait and accept. oneof type { + // Accept fixed channels. FixedChannelRequest fixed = 2; + // Accept connection-oriented channels. ConnectionOrientedChannelRequest basic = 3; + // Accept BLE credit-based channels. CreditBasedChannelRequest le_credit_based = 4; + // Accept enhanced credit-based channels. CreditBasedChannelRequest enhanced_credit_based = 5; } } +// Response of the `OnConnection` method. message OnConnectionResponse { oneof result { CommandRejectReason error = 1; @@ -109,10 +149,13 @@ message OnConnectionResponse { } } +// Request of the `Disconnect` method. message DisconnectRequest { + // Specifies the channel to disconnect. Channel channel = 1; } +// Response of the `Disconnect` method. message DisconnectResponse { oneof result { CommandRejectReason error = 1; @@ -120,10 +163,13 @@ message DisconnectResponse { } } +// Request of the `WaitDisconnection` method. message WaitDisconnectionRequest { + // Specifies the channel to await disconnection. Channel channel = 1; } +// Response of the `WaitDisconnection` method. message WaitDisconnectionResponse { oneof result { CommandRejectReason error = 1; @@ -131,19 +177,27 @@ message WaitDisconnectionResponse { } } +// Request of the `Receive` method. message ReceiveRequest { + // Specifies the channel to fetch data from. Channel channel = 1; } +// Response of the `Receive` method. message ReceiveResponse { + // Contains the data received from the channel. bytes data = 1; } +// Request of the `Send` method. message SendRequest { + // Specifies the channel to send data over. Channel channel = 1; + // Data to be sent over the specified channel. bytes data = 2; } +// Response of the `Send` method. message SendResponse { oneof result { CommandRejectReason error = 1; |