8.2 KiB

Raw Blame History

Gabeldorsche Style Guide

[TOC]

Base

In general, when not mentioned in this document, developers should follow the Google C++ and Google Java style guide as much as possible.

Google C++ Style Guide

C++ Style Guide: https://google.github.io/styleguide/cppguide.html

Android and Google Java Style Guide

Android Java Style Guide: https://source.android.com/setup/contribute/code-style
when not covered by (1), see External Java Style Guide: https://google.github.io/styleguide/javaguide.html

line length limit is 120 characters for C++ and Java

Python Style Guide

The GD stack uses the Google Python Style Guide:

http://google.github.io/styleguide/pyguide.html

with the following modifications as shown in the .style.yapf definition:

based_on_style: google
indent_width: 4
column_limit: 120

Build files

One build target for the entire stack in system/bt (i.e. one cc_library())
- If only part of the stack needs to be compiled, configure it using the “target” configuration in Android.bp
One build target for all unit tests (i.e. one cc_test)
When needed, filgroup() can be created in Android.bp in sub-directories. The main build target should use these filegroups() to build the main output library.
All targets must have host_supported == true unless it is dependent on the OS
If the stack needs to be compiled using other build system, then the build files should also live in system/bt

Namespace and include

Namespace must follow directory names
Top level namespace for internal code is “bluetooth”
Top level namespace for externally visible code is “android::bluetooth”
Include path must be relative to the root directory of the stack. Normally it is system/bt, for GD refactor code, it is system/bt/gd

Multiple implementations of the same header

Since GD interact with many lower level components that are platform dependent, frequently there is need to implement the same header multiple times for different platform or hardware. When doing this:

Avoid #define macros as much as possible. Instead put code into different source files and selectively compile them for different targets.
Convention of operating system used:
- android/
  - All Android devices that use HIDL
- linux/
  - All non-Android linux devices
- linux_generic/
  - Android and non-Android linux devices

Directory structure

Root directory under Android tree: system/bt/gd/

Directory structure should be as flat as possible
Each file should contain at most one class
Header, source code, and unit test should live in the same directory with the following naming guideline:
- Source: bb.cc
- Header: bb.h
- Test: bb_test.cc
Each profile should have its own directory and module
Source and sink, server and client profiles should live in two sub folders of the same common directory where common code can be stored. However, source and sink must have separate modules
Module file is also the external API header
Prefer underscore over dashes

Example: utility library with OS dependent implementation

os/: OS dependent classes such as Alarm, Thread, Handler
- Android.bp: Build file that defines file groups that would include different source files based on compile time target
- alarm.h: common header for alarm
- linux_generic/: Implementations for generic Linux OS
  - alarm.cc: Linux generic implementation of alarm.h using timer_fd
  - alarm_test.cc: unit test for alarm.h
- fuzz/: library needed for fuzz tests in the os/ library

Example: module with hardware dependent implementation

hal/: Hardware abstraction layer such as HCI interfaces, Audio interfaces
- Android.bp: Build file that defines file groups that would include different source files based on compile time target
- hci_hal.h: common library header
- hci_hal_android_hidl.cc: implementation of hci_hal.h using Android HIDL
- hci_hal_android_hidl_test.cc: unit tests for the Android HIDL implementation
- hci_hal_host.cc: implementation of hci_hal.h using root-canal emulator or linux Bluetooth HCI socket
- hci_hal_host_test.cc: unit tests for the socket based HAL (root-canal) emulator implementation
- facade.proto: gRPC automation interface definition for this layer
- facade.h/cc: an implementation of the above gRPC interface for the GD stack
- cert/: certification tests for this module
- fuzz/: library needed for fuzz tests in the hal/ module

Example: similar protocol with the same base

l2cap/: L2CAP layer, splitted among classic and LE
- classic/: Classic L2CAP module
  - cert/: certification tests for this module
  - internal/: internal code to be used only in classic
  - Source code and headers being exported to other modules
- le/: LE L2CAP module
  - cert/: certification tests for this module
  - internal/: internal code to be used only in classic
  - Source code and headers being exported to other modules
- internal/: L2CAP internal code that should not be used by sources outside L2CAP
  - data_pipeline_manager.h
  - data_pipeline_manager.cc
  - data_pipeline_manager_mock.h: Mock of this class, used in unit tests
  - dynamic_channel_allocator.h
  - dynamic_channel_allocator.cc
  - dynamic_channel_allocator_test.cc: GTest unit test of this class
  - dynamic_channel_allocator_fuzz_test.cc: Fuzz test of this class
- *.h/.cc: Common headers and sources that is exposed to other modules

Example: protocol or profiles with client and server side implementations

a2dp/: A2DP profile
- sink/: A2DP sink module (e.g. headset)
- source/: A2DP source module (e.g. phone)
avrcp/
- controller/: AVRCP peripheral module (e.g. carkit)
- target/: AVRCP target module (e.g. Phone)
hfp/
- hf/: Handsfree device (e.g. headset)
- ag/: Audio gateway (e.g. phone)

External libraries

To maintain high portability, we are trying to stick with C++ STL as much as possible. Hence, before including an external library, please ask the team for review.

Examples of currently used libraries:

boringssl: Google's openssl implementation
small parts of libchrome, to be removed or replaced eventually
- base::OnceCallback
- base::Callback
- base::BindOnce
- base::Bind
google-breakpad: host binary crash handler
libbacktrace: print stacktrace on crash on host

Exposed symbols

Given that entire Fluoride library is held in libbluetooth.so dynamic library file, we need a way to load this library and extract entry points to it. The only symbols that should be exposed are:

An entry point to a normal running adapter module libbluetooth.so
A header library to all exposed API service to profiles and layers
An entry point to a certification interface, libbluetooth_certification.so
A header library to this certification stack

Logging

Gabeldorsche uses printf style logging with macros defined in os/log.h. Five log levels are available.

LOG_VERBOSE(fmt, args...): Will be disabled by default
LOG_INFO(fmt, args...): Will be disabled by default
LOG_INFO(fmt, args...): Enabled
LOG_WARN(fmt, args...): Enabled
LOG_ERROR(fmt, args...): Enabled
LOG_ALWAYS_FATAL(fmt, args...): Enabled, will always crash
ASSERT(condition): Enabled, will crash when condition is false
ASSERT_LOG(conditon, fmt, args...): Enabled, will crash and print log when condition is false

In general, errors that are caused by remote device should never crash our stack and should be logged using LOG_WARN() only. Recoverable errors due to our stack or badly behaved bluetooth controller firmware should be logged using LOG_ERROR() before recovery. Non-recoverable errors should be logged as LOG_ALWAYS_FATAL() to crash the stack and restart.

8.2 KiB Raw Blame History