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/packages/modules/Bluetooth/system/+/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 packages/modules/Bluetooth/system (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 packages/modules/Bluetooth/system
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 packages/modules/Bluetooth/system, for GD refactor code, it is packages/modules/Bluetooth/system/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[**packages/modules/Bluetooth/system/gd/**](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/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.cc: implementation of hci_hal.h using linux Bluetooth HCI
117        socket
118    *   hci_hal_host_rootcanal.cc: implementation of hci_hal.h using root-canal
119        emulator
120    *   hci_hal_host_test.cc: unit tests for the socket based HAL (root-canal)
121        emulator implementation
122    *   facade.proto: gRPC automation interface definition for this layer
123    *   facade.h/cc: an implementation of the above gRPC interface for the GD
124        stack
125    *   cert/: certification tests for this module
126    *   fuzz/: library needed for fuzz tests in the hal/ module
127
128### Example: similar protocol with the same base
129
130*   l2cap/: L2CAP layer, splitted among classic and LE
131    *   classic/: Classic L2CAP module
132        *   cert/: certification tests for this module
133        *   internal/: internal code to be used only in classic
134        *   Source code and headers being exported to other modules
135    *   le/: LE L2CAP module
136        *   cert/: certification tests for this module
137        *   internal/: internal code to be used only in classic
138        *   Source code and headers being exported to other modules
139    *   internal/: L2CAP internal code that should not be used by sources
140        outside L2CAP
141        *   data_pipeline_manager.h
142        *   data_pipeline_manager.cc
143        *   data_pipeline_manager_mock.h: Mock of this class, used in unit tests
144        *   dynamic_channel_allocator.h
145        *   dynamic_channel_allocator.cc
146        *   dynamic_channel_allocator_test.cc: GTest unit test of this class
147        *   dynamic_channel_allocator_fuzz_test.cc: Fuzz test of this class
148    *   *.h/.cc: Common headers and sources that is exposed to other modules
149
150### Example: protocol or profiles with client and server side implementations
151
152*   a2dp/: A2DP profile
153    *   sink/: A2DP sink module (e.g. headset)
154    *   source/: A2DP source module (e.g. phone)
155*   avrcp/
156    *   controller/: AVRCP peripheral module (e.g. carkit)
157    *   target/: AVRCP target module (e.g. Phone)
158*   hfp/
159    *   hf/: Handsfree device (e.g. headset)
160    *   ag/: Audio gateway (e.g. phone)
161
162## External libraries
163
164To maintain high portability, we are trying to stick with C++ STL as much as
165possible. Hence, before including an external library, please ask the team for
166review.
167
168Examples of currently used libraries:
169
170*   boringssl: Google's openssl implementation
171*   small parts of libchrome, to be removed or replaced eventually
172    *   base::OnceCallback
173    *   base::Callback
174    *   base::BindOnce
175    *   base::Bind
176*   google-breakpad: host binary crash handler
177*   libunwindstack: print stacktrace on crash on host
178
179## Exposed symbols
180
181Given that entire Fluoride library is held in libbluetooth.so dynamic library
182file, we need a way to load this library and extract entry points to it. The
183only symbols that should be exposed are:
184
185*   An entry point to a normal running adapter module libbluetooth.so
186*   A header library to all exposed API service to profiles and layers
187*   An entry point to a certification interface, libbluetooth\_certification.so
188*   A header library to this certification stack
189
190## Logging
191
192Gabeldorsche uses `printf` style logging with macros defined in `os/log.h`. Five
193log levels are available.
194
195*   LOG_VERBOSE(fmt, args...): Will be disabled by default
196*   LOG_INFO(fmt, args...): Will be disabled by default
197*   LOG_INFO(fmt, args...): Enabled
198*   LOG_WARN(fmt, args...): Enabled
199*   LOG_ERROR(fmt, args...): Enabled
200*   LOG_ALWAYS_FATAL(fmt, args...): Enabled, will always crash
201*   ASSERT(condition): Enabled, will crash when condition is false
202*   ASSERT_LOG(conditon, fmt, args...): Enabled, will crash and print log when
203    condition is false
204
205In general, errors that are caused by remote device should never crash our stack
206and should be logged using LOG_WARN() only. Recoverable errors due to our stack
207or badly behaved bluetooth controller firmware should be logged using
208LOG_ERROR() before recovery. Non-recoverable errors should be logged as
209LOG_ALWAYS_FATAL() to crash the stack and restart.
210