1# Gabeldorsche Style Guide
2
3[TOC]
4
5## Base
6
7In general, when not mentioned in this document, developers should follow the
8Google C++ and Google Java style guide as much as possible.
9
10### Google C++ Style Guide
11
12C++ Style Guide: https://google.github.io/styleguide/cppguide.html
13
14### Android and Google Java Style Guide
15
161.  Android Java Style Guide:
17    https://source.android.com/setup/contribute/code-style
18
192.  when not covered by (1), see External Java Style Guide:
20    https://google.github.io/styleguide/javaguide.html
21
22line length limit is 120 characters for C++ and Java
23
24### Python Style Guide
25
26The GD stack uses the Google Python Style Guide:
27
28*   http://google.github.io/styleguide/pyguide.html
29
30with the following modifications as shown in the
31[.style.yapf](https://android.googlesource.com/platform/system/bt/+/refs/heads/master/.style.yapf) definition:
32
33```yapf
34based_on_style: google
35indent_width: 4
36column_limit: 120
37```
38
39## Build files
40
41*   One build target for the entire stack in system/bt (i.e. one cc_library())
42    *   If only part of the stack needs to be compiled, configure it using the
43        “target” configuration in Android.bp
44*   One build target for all unit tests (i.e. one cc_test)
45*   When needed, filgroup() can be created in Android.bp in sub-directories. The
46    main build target should use these filegroups() to build the main output
47    library.
48*   All targets must have host_supported == true unless it is dependent on the
49    OS
50*   If the stack needs to be compiled using other build system, then the build
51    files should also live in system/bt
52
53## Namespace and include
54
55*   Namespace must follow directory names
56*   Top level namespace for internal code is “bluetooth”
57*   Top level namespace for externally visible code is “android::bluetooth”
58*   Include path must be relative to the root directory of the stack. Normally
59    it is system/bt, for GD refactor code, it is system/bt/gd
60
61## Multiple implementations of the same header
62
63Since GD interact with many lower level components that are platform dependent,
64frequently there is need to implement the same header multiple times for
65different platform or hardware. When doing this:
66
67*   Avoid #define macros as much as possible. Instead put code into different
68    source files and selectively compile them for different targets.
69*   Convention of operating system used:
70    *   android/
71        *   All Android devices that use HIDL
72    *   linux/
73        *   All non-Android linux devices
74    *   linux_generic/
75        *   Android and non-Android linux devices
76
77## Directory structure
78
79Root directory under Android tree:
80[**system/bt/gd/**](https://android.googlesource.com/platform/system/bt/+/refs/heads/master/gd/)
81
82*   Directory structure should be as flat as possible
83*   Each file should contain at most one class
84*   Header, source code, and unit test should live in the same directory with
85    the following naming guideline:
86    *   Source: bb.cc
87    *   Header: bb.h
88    *   Test: bb_test.cc
89*   Each profile should have its own directory and module
90*   Source and sink, server and client profiles should live in two sub folders
91    of the same common directory where common code can be stored. However,
92    source and sink must have separate modules
93*   Module file is also the external API header
94*   Prefer underscore over dashes
95
96### Example: utility library with OS dependent implementation
97
98*   os/: OS dependent classes such as Alarm, Thread, Handler
99    *   Android.bp: Build file that defines file groups that would include
100        different source files based on compile time target
101    *   alarm.h: common header for alarm
102    *   linux_generic/: Implementations for generic Linux OS
103        *   alarm.cc: Linux generic implementation of alarm.h using timer_fd
104        *   alarm_test.cc: unit test for alarm.h
105    *   fuzz/: library needed for fuzz tests in the os/ library
106
107### Example: module with hardware dependent implementation
108
109*   hal/: Hardware abstraction layer such as HCI interfaces, Audio interfaces
110    *   Android.bp: Build file that defines file groups that would include
111        different source files based on compile time target
112    *   hci_hal.h: common library header
113    *   hci_hal_android_hidl.cc: implementation of hci_hal.h using Android HIDL
114    *   hci_hal_android_hidl_test.cc: unit tests for the Android HIDL
115        implementation
116    *   hci_hal_host_rootcanal.cc: implementation of hci_hal.h using root-canal
117        emulator
118    *   hci_hal_host_rootcanal_test.cc: unit tests for the root-canal emulator
119        implementation
120    *   facade.proto: gRPC automation interface definition for this layer
121    *   facade.h/cc: an implementation of the above gRPC interface for the GD
122        stack
123    *   cert/: certification tests for this module
124    *   fuzz/: library needed for fuzz tests in the hal/ module
125
126### Example: similar protocol with the same base
127
128*   l2cap/: L2CAP layer, splitted among classic and LE
129    *   classic/: Classic L2CAP module
130        *   cert/: certification tests for this module
131        *   internal/: internal code to be used only in classic
132        *   Source code and headers being exported to other modules
133    *   le/: LE L2CAP module
134        *   cert/: certification tests for this module
135        *   internal/: internal code to be used only in classic
136        *   Source code and headers being exported to other modules
137    *   internal/: L2CAP internal code that should not be used by sources
138        outside L2CAP
139        *   data_pipeline_manager.h
140        *   data_pipeline_manager.cc
141        *   data_pipeline_manager_mock.h: Mock of this class, used in unit tests
142        *   dynamic_channel_allocator.h
143        *   dynamic_channel_allocator.cc
144        *   dynamic_channel_allocator_test.cc: GTest unit test of this class
145        *   dynamic_channel_allocator_fuzz_test.cc: Fuzz test of this class
146    *   *.h/.cc: Common headers and sources that is exposed to other modules
147
148### Example: protocol or profiles with client and server side implementations
149
150*   a2dp/: A2DP profile
151    *   sink/: A2DP sink module (e.g. headset)
152    *   source/: A2DP source module (e.g. phone)
153*   avrcp/
154    *   controller/: AVRCP peripheral module (e.g. carkit)
155    *   target/: AVRCP target module (e.g. Phone)
156*   hfp/
157    *   hf/: Handsfree device (e.g. headset)
158    *   ag/: Audio gateway (e.g. phone)
159
160## External libraries
161
162To maintain high portability, we are trying to stick with C++ STL as much as
163possible. Hence, before including an external library, please ask the team for
164review.
165
166Examples of currently used libraries:
167
168*   boringssl: Google's openssl implementation
169*   small parts of libchrome, to be removed or replaced eventually
170    *   base::OnceCallback
171    *   base::Callback
172    *   base::BindOnce
173    *   base::Bind
174*   google-breakpad: host binary crash handler
175*   libbacktrace: print stacktrace on crash on host
176
177## Exposed symbols
178
179Given that entire Fluoride library is held in libbluetooth.so dynamic library
180file, we need a way to load this library and extract entry points to it. The
181only symbols that should be exposed are:
182
183*   An entry point to a normal running adapter module libbluetooth.so
184*   A header library to all exposed API service to profiles and layers
185*   An entry point to a certification interface, libbluetooth\_certification.so
186*   A header library to this certification stack
187
188## Logging
189
190Gabeldorsche uses `printf` style logging with macros defined in `os/log.h`. Five
191log levels are available.
192
193*   LOG_VERBOSE(fmt, args...): Will be disabled by default
194*   LOG_DEBUG(fmt, args...): Will be disabled by default
195*   LOG_INFO(fmt, args...): Enabled
196*   LOG_WARN(fmt, args...): Enabled
197*   LOG_ERROR(fmt, args...): Enabled
198*   LOG_ALWAYS_FATAL(fmt, args...): Enabled, will always crash
199*   ASSERT(condition): Enabled, will crash when condition is false
200*   ASSERT_LOG(conditon, fmt, args...): Enabled, will crash and print log when
201    condition is false
202
203In general, errors that are caused by remote device should never crash our stack
204and should be logged using LOG_WARN() only. Recoverable errors due to our stack
205or badly behaved bluetooth controller firmware should be logged using
206LOG_ERROR() before recovery. Non-recoverable errors should be logged as
207LOG_ALWAYS_FATAL() to crash the stack and restart.
208