bt-test-interfaces: Add documentation

Co-authored-by: Thomas Girardier <girardier@google.com>
Change-Id: I60cced9c4a5083e9e42e7ad940f1e5a2c088fec8

4 files changed, 190 insertions, 0 deletions

diff --git a/doc/overview.md b/doc/overview.md
new file mode 100644
index 0000000..c1a1f73
--- /dev/null
+++ b/doc/overview.md
@@ -0,0 +1,49 @@
+Project: /blueberry/_project.yaml
+Book: /blueberry/_book.yaml
+
+# Bluetooth test interfaces
+
+The Bluetooth test interfaces are Remote Procedure Call (RPC) interfaces
+exposed to testing tools to trigger behaviors within a Bluetooth stack under
+test.
+
+While all Bluetooth stacks are different in their supported profiles, features,
+and corresponding APIs, the goal of Blueberry is to provide a set of unified
+test interfaces which they could all implement, so we can reuse and scale
+testing tools and processes across all of them.
+
+## Requirements
+
+Since each Bluetooth stack exposes different APIs, the test interfaces must be
+generic enough and must not rely on any implementation specific behavior.
+However, they must ensure that they provide all the necessary access to the
+existing testing tools. For this reason, the test interfaces are co-designed by
+multiple teams at Google.
+
+The test interfaces must be implemented using [gRPC](https://grpc.io/) services
+and must use [protocol buffers](https://developers.google.com/protocol-buffers)
+as Interface Definition Language (IDL). A Bluetooth stack under test exposing
+such interfaces must thus implement a gRPC server.
+
+The test interfaces definition must follow the [Blueberry style guide](
+style_guide.md).
+
+## Definition level
+
+A test interface is defined for each Bluetooth profile. This allows the
+Bluetooth stack under test to implement only the test interfaces corresponding
+to its supported profiles.
+
+## Optional features
+
+As Bluetooth profiles contain optional features, some methods of the test
+interfaces might not be implementable by a specific Bluetooth stack.
+
+Such unimplemented methods must return an [UNIMPLEMENTED](
+https://grpc.github.io/grpc/core/md_doc_statuscodes.html) status code as defined
+by gRPC.
+
+Discovering which features are supported by a Bluetooth stack is not (yet) part
+of the test interfaces as this is already doable via Bluetooth SIG
+[Implementation Conformance Statements (ICS)](
+https://www.bluetooth.com/specifications/qualification-test-requirements/).
diff --git a/doc/style-guide.md b/doc/style-guide.md
new file mode 100644
index 0000000..c2f793a
--- /dev/null
+++ b/doc/style-guide.md
@@ -0,0 +1,126 @@
+Project: /blueberry/_project.yaml
+Book: /blueberry/_book.yaml
+
+# Style Guide
+
+The Bluetooth test interfaces uses [protocol buffers v3](
+https://developers.google.com/protocol-buffers) as Interfaces Definition
+Language.
+
+All guidelines from the [protocol buffers style guide](
+https://developers.google.com/protocol-buffers/docs/style) apply for them.
+
+## Additional guidelines
+
+A few additional guidelines apply to the Bluetooth test interfaces to guarantee
+consistency and improve readability.
+
+### Use proto3 syntax
+
+The protobuf compiler supports proto2 and proto3 syntax. Proto3 is the
+latest version, we should use it.
+
+### Use names from the Bluetooth specification nomenclature
+
+This avoids adding confusion to naming, even if the names used in the Bluetooth
+specification are not consistent across profiles (Gateway, Target, Controller,
+Server, Client, ...).
+
+```protobuf
+service A2DP {
+    rpc OpenServer(Empty) returns (Empty); // ✗ Avoid
+    rpc OpenSource(Empty) returns (Empty); // ✓ OK
+}
+```
+
+### Name services without prefixes or suffixes
+
+This helps to keep short names, if you need name-spacing you should use
+a package instead.
+
+```protobuf
+service A2DP {} // ✓ OK
+
+service Host {} // ✓ OK
+
+service A2DPServer {} // ✗ Avoid
+
+service BluetoothHost {} // ✗ Avoid
+```
+
+### Avoid long package names
+
+This makes the usage of the gRPC interface harder in some generated language
+where long package names are uncommon, for instance in rust and python.
+
+```protobuf
+package test.interfaces.bluetooth.bredr.l2cap; // ✗ Avoid
+package l2cap; // ✓ OK
+```
+
+### Use standards protocol buffers types
+
+Protocol buffers includes a lot of [well-known types](
+https://developers.google.com/protocol-buffers/docs/reference/google.protobuf),
+so use them instead of redefining your owns.
+
+```protobuf
+rpc L2CAP {
+    Send(MyData) returns (MyEmpty); // ✗ Avoid
+    Send(google.protobuf.BytesValue) returns (google.protobuf.Empty); // ✓ OK
+}
+```
+
+### Describe expected errors with `oneof` fields
+
+This allows using the protocol buffers type system to describe the possible
+outcomes of the request. You don't need to describe all errors, you should only
+specify the ones that are needed by the tests.
+
+We use the [gRPC standard error model](
+https://www.grpc.io/docs/guides/error/#standard-error-model) to send the other
+non specified errors (like implementation specific errors).
+
+```protobuf
+message ConnectResponse {
+    oneof result {
+        Connection connection = 1;
+        DeviceNotFoundError device_not_found = 2;
+        ...
+    }
+}
+```
+
+### Avoid gRPC streaming if possible
+
+There is only a few legitimate usages for gRPC streaming (such as audio
+streaming) and you should avoid it otherwise.
+
+### Use typed tokens to represent a resource
+
+This allows the implementations to wrap their internal format for representing
+the resource inside an opaque message instead of converting them.
+
+```protobuf
+// ✗ Avoid
+service Host {
+    rpc Connect(BdAddr) returns (Handle);
+}
+
+message Handle {
+    int16 handle = 1;
+}
+```
+
+```protobuf
+// ✓ OK
+service Host {
+    rpc Connect(BdAddr) returns (Connection);
+}
+
+message Connection {
+    // Internal (opaque) representation
+    // of the connection by the server
+    bytes cookie = 1;
+}
+```
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..2100c0c
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,6 @@
+# Bluetooth Test Interfaces
+
+This repository contains the definitions of the Bluetooth test interfaces used
+by the Blueberry project.
+
+For more information, see [doc/overview.md](doc/overview.md).
diff --git a/reference.md b/reference.md
new file mode 100644
index 0000000..9e73200
--- /dev/null
+++ b/reference.md
@@ -0,0 +1,9 @@
+Project: /blueberry/_project.yaml
+Book: /blueberry/_book.yaml
+
+# Bluetooth test interfaces reference
+
+This section contains reference documentation for the Bluetooth test interfaces.
+These test interfaces are following Blueberry [requirements](
+/blueberry/guides/bt-test-interfaces/overview) and [style guide](
+/blueberry/guides/bt-test-interfaces/style-guide).