Loading system/gd/rust/linux/docs/glossary.md 0 → 100644 +124 −0 Original line number Diff line number Diff line # Bluetooth Glossary This glossary is for consolidating documentation of terms used throughout Bluetooth codebases. When adding an entry there are a few important considerations to keep in mind: 1. The glossary is not exhaustive - it is sufficient to add a few sentences and link to a full description 2. Readers may be unfamiliar with this domain - keep entries readable to newcomers and if you must use other Bluetooth-specific terminology make sure it is also added in the glossary ## Bluetooth Specification Details of a given profile or protocol may change over time, so descriptions included here are high level to avoid including innaccurate information. As such, specific documents are not linked, but all Bluetooth specification documents can be found on the [Bluetooth website](https://www.bluetooth.com). ### Advacned Audio Distribution Profile Common aliases: A2DP Audio streaming profile for music and other audio. References: A2DP Specification ### Attribute Profile Common aliases: ATT The protocol for describing Bluetooth LE data. References: Core Specification, GATT ### Audio/Video Remote Control Profile Common aliases: AVRCP A profile for allowing a Bluetooth device to control media devices. References: AVRCP Specification ### Generic Access Profile Common aliases: GAP The profile that determines how two Bluetooth devices discover and connect to each other. References: Core Specification ### Generic Attribute Profile Common aliases: GATT Profile for organizing attributes and providing access to them. References: Core Specification ### Hands-Free Profile Common aliases: HFP A superset of HSP and some additional features useful to hands-free interaction with a device. References: HFP Specification, HSP ### Human Interface Device Profile Common aliases: HID, HIDP A wrapper around the USB Human Interface Device (HID) specification used in Bluetooth Classic. References: HID Profile Specification, USB HID Specification ### HID over GATT Profile Common aliases: HOGP Profile for supporting HID devices via the GATT protocol for Bluetooth LE devices. References: HOGP Specification, USB HID Specification ### Headset Profile Common aliases: HSP Profile for enabling headsets that provide audio output and input. References: HSP Specification ### Logical Link Control and Adaptation Layer Protocol Common aliases: L2CAP The communication protocol that most of the Bluetooth stack is built on, similar to UDP. References: Core Specification ### Radio Frequency Communication Protocol common aliases: RFCOMM, rfc[^1] A communication protocol built on top of L2CAP that provides emulated RS-232 communication. References: RFCOMM Specification ## Project Shorthands ### Bluetooth Device Address Common aliases: bda[^1], bdaddr[^1] The unique identification for a Bluetooth device. It is a 48-bit identifier typically expressed in hexadecimal. Notes: It is rarely helpful to refer to these addresses as a Bluetooth Device Address in Bluetooth code as the Bluetooth portion is implied, and "Device" is usually less descriptive than "host", "local", "remote", or a similar term. ## Computing Terminology ### Finite State Machine Common aliases: FSM[^1], State Machine A mechanism for describing the logical flow of a system based on states and transitions. [^1]: These aliases are in use but heavily discouraged as they negatively impact readability system/gd/rust/linux/docs/style_guide.md 0 → 100644 +120 −0 Original line number Diff line number Diff line # Bluetooth Documentation Style Guide This style guide is designed to encourage documentation that maximizes knowledge share and minimizes mental overhead. While this is technically only a documentation style guide, good code is self-documenting so there are many naming conventions stipulated that may result in code changes. ## Acronyms, Abbreviations, and other shortenings Acronyms can often be confusing for those unfamiliar with them. At the same time, effective use of acronyms (and abbreviations) can help to quickly convey information compared to lengthy technical terms (e.g. `logicalLinkControlAndAdaptationLayerProtocol` takes substantially longer to read than `l2cap` and offers no additional clarity if the reader is familiar with the spec). To ensure effective use of these shorthands, follow the guidelines below. 1. Acronyms defined by the Bluetooth specification (e.g. `L2CAP`) may be used anywhere, but the expanded version (e.g. "Logical Link Control and Adaptation Layer") must be added to the [glossary](glossary.md) with an indication of which specification document the reader can consult for more information. * These acronyms may not be shortened in any context (i.e. `RFCOMM` may not be shortened to `rfc`) 2. General computing shorthands (e.g. `tx` instead of `transmit`) are generally allowed and should be added to the [glossary](glossary.md) depending on obscurity at the discretion of code authors and reviewers. * Recommended guideline for ascertaining obscurity: if the definition shows up in the first five Google search results without any additional context it is likely safe to leave it undocumented. Examples: * `mux` is a very common shortening of “multiplexer” and shows up high on search results so documenting is optional * `fsm` is a common shortening of “finite state machine” but does not show up high in search results and should be documented (not to be confused with the Flying Spaghetti Monster which is the first result) 3. Acronyms and abbreviations specific to the codebase are generally discouraged, but permitted and must be documented at the appropriate level of specificity. * Terms used across the codebase should be documented in the [glossary](glossary.md) * Terms used within specific files or directories only may be documented in that file or directory * Names of enums, structs, traits, files, etc. <b>must<b> be completely spelled out (except for Bluetooth Specification acronyms) 4. In documentation files the first occurrence of ALL acronyms should be spelled out. * Example: you can refer to Three Letter Acronyms (TLAs) as simply TLAs in the rest of the document ## Citations Much of the logic within Floss is dictated by the Bluetooth Specification. Citing the individual sections of the specification that informed decisions makes it easier for the reader to understand why code is structured the way it is and aids debugging efforts. In general, any comments or explanations should be limited to the code’s structure (“the spec requires that this field be of length X”) and *not* why the specification makes certain requirements (“This field has a length of X to accommodate Y and Z with a parity bit as per the specification”) unless the code is directly related to those details (a parser for a field may benefit from having an explanation of the structure of the data it is meant to manipulate). In code: ```cpp // This is the maximum allowed size for this field. // Bluetooth Core Specification Version 2.8, Volume 57, Part Z, Section 15 ``` In documentation (markdown): ```md The order of these operations is required by the Bluetooth Core Spec[^ordering] [^ordering]: Bluetooth Core Specification Version 2.8, Volume 57, Part Z, Section 15 ``` ## Top-of-file documentation All files should have a comment block preceding and code (except includes) which explains the purpose of the file and covers other meta-information that may be useful to a reader. There are no strict requirements for how this should be structured, but the following information should be covered. 1. A short summary of what is included in the file 2. Any relevant parts of the specification that the reader should be familiar with * It is not necessary to enumerate everything that might be relevant * If the file primarily contains the implementation of a profile, it is helpful to the reader to have a link to that specification 3. If the file is a “main” file as part of an executable it should contain high-level information about: * The purpose of the executable * Usage information (unless the usage is self-documenting) * Architectural overviews such as threading models and state machines 4. It is not necessary to go into details beyond what is needed for a reader to be able to navigate the code. If something is necessary but is itself very complex it is permissible to link to the documentation for that piece of code. * Example: an executable relies heavily on a complex state machine to function, to the extent that anyone trying to read the code should be familiar with it. The executable’s main file should have a short (less than one paragraph) explanation of the state machine’s role and then link to the file that contains the state machine (which should also be documented). ## Dependency Documentation Whenever documentation depends on the reader understanding how a different system or code functions, prefer to write a brief description (1-2 sentences) of why that system is necessary or how it is being used, and leave details of the function of that system out. It is heavily encouraged to update a dependency's documentation as needed. ## System Documentation Developers expect to find README files that explain the purpose of a given project and various meta-details about it. This can include build instructions or usage instructions, as well as information about how to contribute, and more. All of Floss’s binaries should have such information documented in a README file. Documentation authors have discretion to decide how much of this information belongs in a binary’s main file, a binary’s top-level directory, or in a project-level README. Loading
system/gd/rust/linux/docs/glossary.md 0 → 100644 +124 −0 Original line number Diff line number Diff line # Bluetooth Glossary This glossary is for consolidating documentation of terms used throughout Bluetooth codebases. When adding an entry there are a few important considerations to keep in mind: 1. The glossary is not exhaustive - it is sufficient to add a few sentences and link to a full description 2. Readers may be unfamiliar with this domain - keep entries readable to newcomers and if you must use other Bluetooth-specific terminology make sure it is also added in the glossary ## Bluetooth Specification Details of a given profile or protocol may change over time, so descriptions included here are high level to avoid including innaccurate information. As such, specific documents are not linked, but all Bluetooth specification documents can be found on the [Bluetooth website](https://www.bluetooth.com). ### Advacned Audio Distribution Profile Common aliases: A2DP Audio streaming profile for music and other audio. References: A2DP Specification ### Attribute Profile Common aliases: ATT The protocol for describing Bluetooth LE data. References: Core Specification, GATT ### Audio/Video Remote Control Profile Common aliases: AVRCP A profile for allowing a Bluetooth device to control media devices. References: AVRCP Specification ### Generic Access Profile Common aliases: GAP The profile that determines how two Bluetooth devices discover and connect to each other. References: Core Specification ### Generic Attribute Profile Common aliases: GATT Profile for organizing attributes and providing access to them. References: Core Specification ### Hands-Free Profile Common aliases: HFP A superset of HSP and some additional features useful to hands-free interaction with a device. References: HFP Specification, HSP ### Human Interface Device Profile Common aliases: HID, HIDP A wrapper around the USB Human Interface Device (HID) specification used in Bluetooth Classic. References: HID Profile Specification, USB HID Specification ### HID over GATT Profile Common aliases: HOGP Profile for supporting HID devices via the GATT protocol for Bluetooth LE devices. References: HOGP Specification, USB HID Specification ### Headset Profile Common aliases: HSP Profile for enabling headsets that provide audio output and input. References: HSP Specification ### Logical Link Control and Adaptation Layer Protocol Common aliases: L2CAP The communication protocol that most of the Bluetooth stack is built on, similar to UDP. References: Core Specification ### Radio Frequency Communication Protocol common aliases: RFCOMM, rfc[^1] A communication protocol built on top of L2CAP that provides emulated RS-232 communication. References: RFCOMM Specification ## Project Shorthands ### Bluetooth Device Address Common aliases: bda[^1], bdaddr[^1] The unique identification for a Bluetooth device. It is a 48-bit identifier typically expressed in hexadecimal. Notes: It is rarely helpful to refer to these addresses as a Bluetooth Device Address in Bluetooth code as the Bluetooth portion is implied, and "Device" is usually less descriptive than "host", "local", "remote", or a similar term. ## Computing Terminology ### Finite State Machine Common aliases: FSM[^1], State Machine A mechanism for describing the logical flow of a system based on states and transitions. [^1]: These aliases are in use but heavily discouraged as they negatively impact readability
system/gd/rust/linux/docs/style_guide.md 0 → 100644 +120 −0 Original line number Diff line number Diff line # Bluetooth Documentation Style Guide This style guide is designed to encourage documentation that maximizes knowledge share and minimizes mental overhead. While this is technically only a documentation style guide, good code is self-documenting so there are many naming conventions stipulated that may result in code changes. ## Acronyms, Abbreviations, and other shortenings Acronyms can often be confusing for those unfamiliar with them. At the same time, effective use of acronyms (and abbreviations) can help to quickly convey information compared to lengthy technical terms (e.g. `logicalLinkControlAndAdaptationLayerProtocol` takes substantially longer to read than `l2cap` and offers no additional clarity if the reader is familiar with the spec). To ensure effective use of these shorthands, follow the guidelines below. 1. Acronyms defined by the Bluetooth specification (e.g. `L2CAP`) may be used anywhere, but the expanded version (e.g. "Logical Link Control and Adaptation Layer") must be added to the [glossary](glossary.md) with an indication of which specification document the reader can consult for more information. * These acronyms may not be shortened in any context (i.e. `RFCOMM` may not be shortened to `rfc`) 2. General computing shorthands (e.g. `tx` instead of `transmit`) are generally allowed and should be added to the [glossary](glossary.md) depending on obscurity at the discretion of code authors and reviewers. * Recommended guideline for ascertaining obscurity: if the definition shows up in the first five Google search results without any additional context it is likely safe to leave it undocumented. Examples: * `mux` is a very common shortening of “multiplexer” and shows up high on search results so documenting is optional * `fsm` is a common shortening of “finite state machine” but does not show up high in search results and should be documented (not to be confused with the Flying Spaghetti Monster which is the first result) 3. Acronyms and abbreviations specific to the codebase are generally discouraged, but permitted and must be documented at the appropriate level of specificity. * Terms used across the codebase should be documented in the [glossary](glossary.md) * Terms used within specific files or directories only may be documented in that file or directory * Names of enums, structs, traits, files, etc. <b>must<b> be completely spelled out (except for Bluetooth Specification acronyms) 4. In documentation files the first occurrence of ALL acronyms should be spelled out. * Example: you can refer to Three Letter Acronyms (TLAs) as simply TLAs in the rest of the document ## Citations Much of the logic within Floss is dictated by the Bluetooth Specification. Citing the individual sections of the specification that informed decisions makes it easier for the reader to understand why code is structured the way it is and aids debugging efforts. In general, any comments or explanations should be limited to the code’s structure (“the spec requires that this field be of length X”) and *not* why the specification makes certain requirements (“This field has a length of X to accommodate Y and Z with a parity bit as per the specification”) unless the code is directly related to those details (a parser for a field may benefit from having an explanation of the structure of the data it is meant to manipulate). In code: ```cpp // This is the maximum allowed size for this field. // Bluetooth Core Specification Version 2.8, Volume 57, Part Z, Section 15 ``` In documentation (markdown): ```md The order of these operations is required by the Bluetooth Core Spec[^ordering] [^ordering]: Bluetooth Core Specification Version 2.8, Volume 57, Part Z, Section 15 ``` ## Top-of-file documentation All files should have a comment block preceding and code (except includes) which explains the purpose of the file and covers other meta-information that may be useful to a reader. There are no strict requirements for how this should be structured, but the following information should be covered. 1. A short summary of what is included in the file 2. Any relevant parts of the specification that the reader should be familiar with * It is not necessary to enumerate everything that might be relevant * If the file primarily contains the implementation of a profile, it is helpful to the reader to have a link to that specification 3. If the file is a “main” file as part of an executable it should contain high-level information about: * The purpose of the executable * Usage information (unless the usage is self-documenting) * Architectural overviews such as threading models and state machines 4. It is not necessary to go into details beyond what is needed for a reader to be able to navigate the code. If something is necessary but is itself very complex it is permissible to link to the documentation for that piece of code. * Example: an executable relies heavily on a complex state machine to function, to the extent that anyone trying to read the code should be familiar with it. The executable’s main file should have a short (less than one paragraph) explanation of the state machine’s role and then link to the file that contains the state machine (which should also be documented). ## Dependency Documentation Whenever documentation depends on the reader understanding how a different system or code functions, prefer to write a brief description (1-2 sentences) of why that system is necessary or how it is being used, and leave details of the function of that system out. It is heavily encouraged to update a dependency's documentation as needed. ## System Documentation Developers expect to find README files that explain the purpose of a given project and various meta-details about it. This can include build instructions or usage instructions, as well as information about how to contribute, and more. All of Floss’s binaries should have such information documented in a README file. Documentation authors have discretion to decide how much of this information belongs in a binary’s main file, a binary’s top-level directory, or in a project-level README.
