From de95d2a076bb2111aef75afa7fb9496016e4bc72 Mon Sep 17 00:00:00 2001 From: Mary Ruthven Date: Tue, 5 Jan 2021 16:37:30 -0800 Subject: coil: remove docs that go in the EC This code uses coil terms we're removing, but we don't use it in platform/cr50. Remove the code instead of replacing the terms. BUG=b:175244613 TEST=make buildall -j Change-Id: I2470f37fefb8b109efa1fb6126c9fa3a00bfcd3e Signed-off-by: Mary Ruthven Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2613450 Reviewed-by: Namyoon Woo --- docs/ec_terms.md | 26 +- .../fingerprint-authentication-design-doc.md | 762 --------------------- docs/fingerprint/fingerprint-dev-for-partners.md | 530 -------------- docs/fingerprint/fingerprint.md | 242 ------- docs/low_battery_startup.md | 428 ------------ docs/sitemap.md | 12 - docs/usb-c.md | 222 ------ docs/usb_power.md | 250 ------- 8 files changed, 1 insertion(+), 2471 deletions(-) delete mode 100644 docs/fingerprint/fingerprint-authentication-design-doc.md delete mode 100644 docs/fingerprint/fingerprint-dev-for-partners.md delete mode 100644 docs/fingerprint/fingerprint.md delete mode 100644 docs/low_battery_startup.md delete mode 100644 docs/usb-c.md delete mode 100644 docs/usb_power.md diff --git a/docs/ec_terms.md b/docs/ec_terms.md index 6a19b4e055..fb6d42619c 100644 --- a/docs/ec_terms.md +++ b/docs/ec_terms.md @@ -64,10 +64,6 @@ switching, sensor management, and other functions, offloading these tasks from the [AP](#ap). -* **E-Mark - Electronically Marked Cable** {#emark} - - See the [USB-C documentation](./usb-c.md#emark) for more details. - * **eSPI - Enhanced Serial Peripheral Interface (Intel)**{#espi} Intel's synchronous communication interface between the [AP](#ap) and the @@ -142,18 +138,10 @@ video streams from a single display port. The EC code is typically responsible for enabling and disabling the MST hub chipset. -* **PD - USB Power Delivery**{#pd} - - See the [USB-C documentation](./usb-c.md#pd) for more details. - * **PMIC - Power Management IC**{#pmic} An integrated circuit used to turn power rails on and off. -* **PPC - USB Power Path Controller**{#ppc} - - See the [USB-C documentation](./usb-c.md#ppc) for more details. - * **PWM - Pulse Width Modulation**{#pwm} Method of varying the duty cycle of a signal to control another device. A @@ -170,14 +158,6 @@ more bytes on the MISO signal, and de-assertion of the chip select. The contents of a SPI frame varies based on the SPI slave type. -* **SVDM - Structured Vendor Defined Messages**{#svdm} - - See the [USB-C documentation](./usb-c.md#svdm) for more details. - -* **TCPC - USB Type-C Port Controller**{#tcpc} - - See the [USB-C documentation](./usb-c.md#tcpc) for more details. - * **UART - Universal Asynchronous Receiver Transceiver**{#uart} Also known as a serial port. An asynchronous communication channel between @@ -187,10 +167,6 @@ second). Typical use is to provide a debug console to the EC. [RS-232] is the protocol standard used by UARTs. -* **VCONN - Connector Voltage** {#vconn} - - See the [USB-C documentation](./usb-c.md#vconn) for more details. - [BC 1.2 Specification]: [CrOS Board Info]: @@ -199,4 +175,4 @@ [eSPI Specification]: [I2C Specification]: [RS-232]: -[EC MKBP driver]: \ No newline at end of file +[EC MKBP driver]: diff --git a/docs/fingerprint/fingerprint-authentication-design-doc.md b/docs/fingerprint/fingerprint-authentication-design-doc.md deleted file mode 100644 index eab2ccabf9..0000000000 --- a/docs/fingerprint/fingerprint-authentication-design-doc.md +++ /dev/null @@ -1,762 +0,0 @@ -# Fingerprint Authentication on Chrome OS - -Authors: norvez@google.com, vpalatin@google.com - -Reviewers: kerrnel@google.com, mnissler@google.com - -Last Updated: 2019-01-14 - -[TOC] - -## Objective - -### Goals - -* Let users securely unlock their device with just their fingerprint -* Reuse the same architecture on all future platforms, don’t be tied to a - specific technology ([Arm TrustZone], [Intel SGX]). -* Support Android’s [fingerprint authentication framework] so users can for - example authorise payments in Android apps with their fingerprint. The - fingerprint implementation needs to comply with Android’s [CDD]. - -### Non-goals - -* Let users log in with their fingerprint - * Users will have to use other authentication methods (e.g. password or - PIN) to log into their account. - * Once logged in, users will be able to unlock the screen with their - fingerprint - -## Background - -To unlock their Chromebook users have to enter their password or a PIN. -[Windows] and [macOS] let the user authenticate with their fingerprint for -faster unlocking, we want to bring that capability to Chrome OS. - -### Fingerprint matching basics - -#### Fingerprint enrollment - -When a user wants to register their finger for fingerprint authentication, they -go through the _enrollment_ operation. They are asked to touch the sensor -multiple times with different parts of their fingerprint. The -[matching algorithm] uses the images captured during enrollment to build a model -of that fingerprint (known as a _template_). - -#### Fingerprint matching - -When the user puts their finger on the sensor, an image of the fingerprint is -captured and compared to the fingerprint templates of the enrolled fingerprints -to determine if the fingerprint matches one of the templates. - -#### Template update (TU) - -When the matching algorithm determines that a fingerprint matches a template -with a high level of certainty, it can (and normally will) use that fingerprint -image to update the template to improve the accuracy of future matching -operations. - -### Threat model - -There are two main objectives for potential attackers: - -* Large scale collection of biometric data from users by opportunistic - attackers - * This attack is only valuable remotely. In case an attacker has physical - access to the device they are already able to collect fingerprint data - left by the user on the device itself without having to attack the - software. -* Target a specific user, typically with physical access to the device in - order to either: - * Allow the attacker to enroll their own fingerprint to unlock the device - at will later on (the “abusive partner” model). - * Spoof positive fingerprint matches to let the rest of the system believe - that a user has successfully identified, for example to break [2FA] - \("spy" trying to gain access to an organisation’s resources via the - victim’s computer). - -### Privacy and security - -* Biometric data is particularly sensitive, so all operations on fingerprint - data must happen in a _Secure Biometric Processor_ (**SBP**). Attackers must - not gain access to the user’s fingerprints even if they have exploited the - software running on the AP. -* To protect the user’s privacy, fingerprint data must not be accessible - without the user’s consent, even by Google. Typically it will protected by - the user’s password. -* Fingerprint data must not leave the device. -* For added security, only the specific Chromebook used to enroll the - fingerprint can use it. Other Chromebooks, even of the same model, must not - be able to use the enrolled fingerprint. - -### Scalability - -For Eve, we [considered][Old Design Doc] using SGX as the SBP. -However the complexity of the solution makes that option unattractive, both -because of the amount of dev work required and because of the large resulting -attack surface. It’s also exclusive to Intel, we would have to develop a -completely different architecture for other platforms, which would add more dev -work and increase the attack surface again. - -## Overview {#overview} - -Devices have a dedicated microcontroller (MCU) running a firmware based on the -[Chromium OS EC] codebase that is used as the _Secure Biometric Processor_ -(**SBP**), where all enrollment and matching operations take place. Even if -attackers gained control of the AP, they still would not be able to access the -fingerprint (FP) data since it never leaves the SBP unencrypted. - -The SBP controls the sensor directly over a dedicated SPI bus. The SBP is -connected to the host with a different SPI bus, the host has no direct access to -the FP data coming from the sensor. - -Enrolled templates for a particular user are stored in the user’s [cryptohome] -but not synced/backed up to the cloud. They are thus encrypted with a key -(`User_Key`) derived from the user’s password, preventing 3rd parties (including -Google) from accessing the fingerprint templates if the user hasn’t entered -their password. - -On top of that, enrolled templates are also encrypted by a device-specific -`HW_Key`. `HW_Key` is derived from a secret that has been randomly generated by -the SBP, which prevents decrypting the templates on another device. - -### Architecture - -![Fingerprint Architecture] - -### Typical workflows - -#### FP enrollment - -1. User starts the enrollment flow from the Settings UI. -1. SBP starts the enrollment operation. -1. SBP captures a number of FP images (exact number depends on the sensor, - typically 3-4 to 10-12) and builds the template in the SBP’s volatile memory -1. SBP encrypts the template with `HW_Key` and sends the encrypted template to - the AP. -1. AP encrypts the template with `User_Key` and saves it to non-volatile - storage. -1. User goes back to step 1 to enroll another finger. A user can typically - enroll 3 to 5 fingers, depending on how many templates the SBP can hold in - its internal volatile storage at the same time. - -#### User login - -1. User logs in by typing their password. -1. FP templates of that user go through the first level of decryption, with - `User_Key`. -1. FP templates are uploaded to the SBP. -1. FP templates go through the second level of decryption in the SBP, with - `HW_Key`. -1. Deciphered FP templates are kept in the SBP’s volatile memory, ready to use - for matching operations. - -#### Screen unlocking operation - -1. User touches the sensor with their finger. -1. SBP verifies that the FP image matches one of the user’s templates. -1. SBP wakes up the AP and sends a “FP matched” message to the AP -1. The AP unlocks the screen. -1. Matcher updates the template in the SBP’s volatile memory. -1. SBP encrypts the updated template with `HW_Key` and sends the encrypted - template to the AP. -1. AP encrypts the template with `User_Key` and saves it to non-volatile - storage. - -## Detailed Design {#detailed-design} - -### FP template encryption {#template-encryption} - -FP templates are encrypted "twice". First, the templates are encrypted by the -SBP with a hardware-bound key that is unique to this SBP and that only the SBP -knows. On top of that, the AP also encrypts the FP templates with a key bound to -the user password. - -#### User-bound encryption - -The FP templates are stored in a "[cryptohome daemon store folder]" which is -encrypted by [cryptohome] with a key tied to the user password. We plan to -replace this post-launch with a mechanism similar to -[Authentication-Time User Secrets]. Separate design doc to come. - -#### Hardware-bound encryption - -FP templates are AES-encrypted with `HW_Key`. `HW_Key` is bound to this specific -SBP so encrypted templates can only be deciphered by this specific SBP. To -ensure that a powerwash/recovery/WP toggle/.../ makes the encryption key -impossible to recover, `HW_Key` also depends on a secret held by the TPM. - -We use an AEAD cipher (AES-GCM) to detect if the encrypted templates have been -tampered with by an attacker controlling the AP. - -##### SBP secret generation - -The SBP generates a new 128-bit random number `SBP_Src_Key` every time the user -goes through recovery or powerwashes the device. The [clobber-state] script -sends a command to the SBP to make it immediately regenerate a new `SBP_Src_Key` -immediately after requesting a TPM clear. - -`SBP_Src_Key` is stored by the SBP’s internal Flash and never shared with the -AP. - -##### TPM-held Secret - -To avoid potential bugs where `SBP_Src_Key` would not always be made -unrecoverable in some corner cases of recovery or powerwash, we make the -encryption key `HW_Key` depend on a secret that is held by the TPM and deleted -every time the TPM is cleared, for example if someone attempts to do a -"[ccd open]" to disable the hardware WP. - -The following is a summary of the mechanism, see the specific design doc -[“TPM-seed for Fingerprint MCU”] for details. - -The TPM already holds a "[system key]" `Cros_Sys_Key` in NVRAM space that is -used to derive the encryption key of the stateful partition. That "system key" -can only be read once per boot, typically by [mount_encrypted]. - -We modify mount_encrypted so that right after reading the seed, it derives a key -`TPM_Seed`: - -``` -TPM_Seed = HMAC-SHA256(Cros_Sys_Key, "biod") -``` - -`TPM_Seed` is then uploaded to the SBP where it will part of the -[Input Key Material (IKM)] and immediately cleared from the AP’s memory, while -the attack surface is very small (e.g. no network connections, stateful -partition not yet mounted) to prevent attackers from accessing it. - -##### `HW_Key` derivation {#hw-key-derivation} - -The `HW_Key` 128-bit AES key for every FP template on the device is derived from -the SBP’s secret and the TPM’s secret to ensure uniqueness. Therefore, even two -identical devices would have different encryption keys. The user ID is also used -as an input for key derivation, so 2 users on the same device won’t share -encryption keys either. Summing up, the key used to encrypt a template depends -on: - -* Device-bound `TPM_Seed`, randomly generated on recovery/powerwash -* SBP-specific `SBP_Src_Key`, randomly generated on recovery/powerwash -* User ID on the device -* Encryption salt, randomly generated before every encryption - -###### Salt for key derivation - -Every time we update a template, we generate a new random 128-bit salt. - -The salt is not required to be secret, so we store `User_Salt` in cleartext next -to the user’s encrypted FP templates on the disk. - -On user login, biod sends the salt and the encrypted FP templates to the SBP. -biod also sends the User ID to the SBP. The SBP derives the AES key using [HKDF] -with HMAC-SHA256: - -``` -HW_Key = HKDF(HMAC-SHA256, SBP_Src_Key, TPM_Seed, User_Salt, User_ID) -``` - -At that point, the SBP [authenticates and deciphers](#aead) the FP templates. -The SBP then generates a new 128-bit salt `User_Salt_New` randomly and derives a -new AES key: - -``` -HW_Key_New = HKDF(HMAC-SHA256, SBP_Src_Key, TPM_Seed, User_Salt_New, User_ID) -``` - -Updated FP templates are then encrypted with `HW_Key_New` before being stored on -the host, along with the new salt `User_Salt_New`. - -*Note*: The SBP has a unique serial number hwID that could also be used as an -additional input to the KDF (though it never changes). The entropy is pretty low -and though not easily accessible an attacker who had stolen the device could -gain access to it. After consulting with the security team, using the hwID was -deemed unnecessary since it wasn’t adding real entropy. - -##### AEAD (AES-GCM) Encryption {#aead} - -To encrypt the FP templates with `HW_Key` we use BoringSSL’s implementation of -AES-GCM128. - -###### Initialisation Vector - -The encryption operations are done by the R/W firmware that doesn’t have write -access to the Flash, so it can’t keep track of IVs that could have already been -used during previous boots since it has no way to persist state. Instead, the -SBP will generate a random 96-bit IV every time it needs to encrypt a template -with `HW_Key` before sending it back to the host for storage. This only happens -every time a user successfully matches their finger, which assuming 1 match -every second for 10 years would result in 3600\*24\*365\*10 < 350,000,000, so -the risk of reusing an IV is acceptable. To ensure that a compromised host could -not try to generate too many messages to find collisions, the SBP rate-limits -the number of encryption operations to 1 per second. - -The IV will be stored on the host with the salt, the encrypted templates and the -16-byte tag for authentication. - -###### Authentication Tag - -To authenticate the encrypted templates, we use a 128-bit tag that we store in -clear text with the encrypted template. - -Authentication of the encrypted templates prevents attackers from generating -random templates to try to attack directly the matching libraries rather than -the AES-GCM128 implementation. It also prevents attackers from trying to pass -their own template instead of the user’s FP template. - -###### Encryption Flowchart - -Encryption of the FP template in the SBP before the ciphered data is sent to the -AP for storage. - -![Encryption Flowchart] - -###### Decryption Flowchart - -Decryption of the ciphered FP template coming from the AP when the user logs in. - -![Decryption Flowchart] - -#### FP template disk format - -Encrypted templates are stored in a “[cryptohome daemon store folder]” that is -only mounted/decrypted when the user has logged in. The templates are stored as -JSON files with the following fields: - -```JSON -{ - "biomanager": “CrosFpBiometricsManager” string - "version": integer describing the version of the file format. Set to 1 at launch - "data": Base64-encoded string containing the `HW_Key`-encrypted template - "label": user-configurable human-readable string listed in the UI - "record_id": UUID of that template generated at enrollment time -} -``` - -##### `HW_Key`-encrypted template format - -The content of the "data" field is the encrypted template that can be deciphered -by the SBP. - -| Field Name | Field description | Field size (bytes) | Field offset (bytes) | -| ---------- | ------------------ | ------------------ | -------------------- | -| Version | Number describing the version of the file format. Set to 3 at launch. | 2 | 0 | -| Reserved | Reserved bytes, set to 0 | 2 | 2 | -| Nonce | Randomly-generated IV | 12 | 4 | -| Salt | Randomly-generated salt | 16 | 16 | -| Tag | AES-GCM Authentication Tag | 16 | 32 | -| Template | Encrypted template | 47552 | 48 | - -When the user logs in, the cryptohome daemon store folder of that user is -mounted and the JSON files become available to biod. For every enrolled finger, -biod sends the `HW_Key`-encrypted template to the SBP. The SBP -[derives `HW_Key`](#hw-key-derivation) for that template and deciphers the -template. - -### Protection of the SBP - -To access the unencrypted data and/or `HW_Key`, attackers have 3 main options: - -* Temporarily gain read or even execution access in the SBP through a firmware - bug - * Would allow an attacker to gain access to the clear text FP data and/or - the encryption key - * Mitigation strategy in [Prevent RW exploits](#prevent-rw-exploits) -* Turn a temporary compromise of the SBP’s firmware into a permanent exploit - by replacing the SBP’s firmware with a firmware controlled by the attacker - * Would allow an attacker to gain access to the clear text FP data and/or - the encryption key - * Would allow an attacker to spoof positive FP matches, defeating 2FA - * Mitigation in [Verified firmware](#verified-firmware) -* Use physical access and control of WP to load a compromised firmware to the - SBP - * Mitigation in [Control WP/BOOT0](#control-wp-boot0) - -#### Verified firmware {#verified-firmware} - -To verify the integrity of the firmware we use a mechanism similar to the one -used to protect the EC in detachable keyboards as described in -[Detachable Base Verified Boot]. - -The SBP has a minimalistic RO firmware that contains the public part of an -RSA-3072 exponent 3 key pair. The corresponding private key is only accessible -by the Chrome OS signers and is used to sign SBP firmwares. On boot the RO -firmware verifies the signature of the RW firmware. If the RW signature is -valid, the RO firmware protects itself by setting the WP bit of the Flash then -jumps to RW. - -##### Anti-rollback - -On top of verifying the signature of the RW firmware, the RO firmware must -verify that the RW firmware is not an outdated version with known -vulnerabilities. This is required to prevent attackers from loading valid but -vulnerable RW firmwares. This is achieved with an anti-rollback mechanism as -described in -[Detachable Base Verified Boot][Detachable Base Verified Boot Anti-Rollback]. - -###### Nocturne-specific anti-rollback - -On nocturne, the SBP is an STM32H7 MCU, with 128K Flash blocks. We still need 2 -pingpong RB blocks to prevent data loss, so the Flash map looks like this: - -Name | Size -------------------- | ------- -RO firmware | 128 KB -Blank | 640 KB -RB1 + `SBP_Src_Key` | 128 KB -RB2 + `SBP_Src_Key` | 128 KB -RW firmware | 1024 KB - -The Nocturne SBP uses the same Flash block for the anti-rollback mechanism and -`SBP_Src_Key`. Most of the anti-rollback mechanism is identical to the one -described in -[Detachable Base Verified Boot][Detachable Base Verified Boot Anti-Rollback], -and the key is similar to the entropy/secret stored for -[Detachable Base Swap Detection]. - -The rollback minimum version is updated whenever RO has verified RW signature, -and the RW rollback version is larger than what is stored in the RB block. - -When re-keying is desired, `SBP_Src_Key` is updated by doing the following -operation: - -``` -SHA256(SBP_Src_Key || entropy) -``` - -where `entropy` is generated from STM32H7 True Random Number Generator (see -[RM0433] Chapter 33 for details). Since there are 2 rollback blocks, and we -ping-pong between them, re-keying should involve updating `SBP_Src_Key` twice, -so that both blocks are erased, and no remnant of the previous key is left over. - -#### Prevent RW exploits {#prevent-rw-exploits} - -Even non-persistent exploits in the RW firmware would be problematic if the -attacker was able to read the content of the memory or the Flash, e.g. via a -buffer overflow, since they could gain access to the clear text FP data and/or -the encryption key. If the attacker was also able to execute code in RW, they -would be able to spoof positive FP matches. - -##### Attack through host command interface {#attack-host-command} - -The AP can send a number of commands to the SBP, for example to wait for a match -or to update the RW firmware. In case of a vulnerability in the protocol an -attacker with (potentially remote) access to the AP<->SBP SPI bus could send bad -specially crafted commands to the SBP and potentially gain read, write or even -execute permissions in the SBP. - -###### Mitigation strategies - -* Limit the size of the API exposed by the SBP to the AP -* Fuzz the host command interface - -##### Attack through crafted templates uploaded to the SBP {#template-attack} - -The AP partially deciphers (with `User_Key`) the templates stored on the disk -then sends the `HW_Key`-encrypted templates to the SBP where they will be -deciphered and then passed to the matching algorithm. An attacker could submit a -carefully crafted template to the SBP that would exploit holes in the closed -source matching algorithm library. - -###### Mitigation strategies - -We use AEAD to decipher and authenticate the templates received from the AP, -they are not passed directly to the matching library. Bad templates will be -intercepted by the decryption code. - -##### RAM noexec - -Even if an attacker gained some level of access to the SBP, the RAM is not -executable so it would be hard for the attacker to execute compromised code, for -example to spoof successful authentication and break 2FA or to attempt to turn -into a persistent compromission of the SBP by writing a new compromised firmware -to Flash. - -#### Control WP/BOOT0 {#control-wp-boot0} - -The BOOT0 pin of the MCU is gated by the WP controlled by Haven. Since toggling -the WP bit from Haven requires physical access to the device, remote attackers -can’t toggle the BOOT0 pin to make the MCU start in bootloader mode and -read/write the Flash from the AP. - -However, with physical access (> 5 minutes) an attacker could disable the WP -signal from Haven and toggle the BOOT0 pin to start the MCU in bootloader mode. - -##### Flash protected with RDP Level 1 - -We will set the Flash in [Global Read-out Protection (RDP) mode Level 1]. This -means that attackers with physical access who would manage to start the MCU in -bootloader mode would not be able to read `SBP_Src_Key` from the Flash. -Attackers would still be able to read the content of the RAM and registers but -at that point the MCU would just have rebooted and the RAM would be empty. - -If the attacker attempted to write their own code to the Flash (for example to -replace RO), RDP Level 1 would only allow that after a complete erasure of the -Flash that would wipe `SBP_Src_Key`, preventing the user from decrypting FP -templates. - -*Note*: An attacker with that level of access could in theory replace the RO -firmware with their own firmware. This would however have wiped enrolled -fingers, giving the user an indication that their device might have been -tampered with. This wouldn’t give access to existing FP templates or images to -the attacker, only future enrollments. - -##### RMA - -To ensure that a device is clean after e.g. refurbishing, the RMA procedure -would require that the operator disabled the WP bit from Haven and toggled BOOT0 -to switch to bootloader mode. After that a known good RO and RW firmware can be -written to the Flash and the operator will reenable the WP bit from Haven. - -## Security Considerations - -### Security boundaries - -#### Chrome to system services - -Biod and Chrome communicate over D-Bus (defined [here][biod D-Bus API]). - -* Chrome lets biod know when the user has signed in, so biod can load the - templates to the [SBP](#overview). -* Biod lets Chrome know when the SBP has detected a positive or negative match - so Chrome can unlock the screen. -* Chrome tells biod to start/end enrolling a finger. -* Chrome tells biod to start/end authentication (matching) mode. - -#### Kernel to firmware - -The SBP uses the `cros_ec` interface, same as the EC. There are additional -SBP-specific host commands that the AP can send to the SBP, see -[Attack through host command interface](#attack-host-command). - -### Privileges - -#### Sandboxing - -Biod uses Minijail ([upstart script][biod upstart script]) for [sandboxing], and -has a [seccomp filter]. - -### Untrusted input - -Encrypted templates are read from the stateful partition where they could be -corrupted or tampered with. Biod itself doesn’t parse that input -it’s still -encrypted by the SBP- and merely marshalls the data around to and from the SBP. -To ensure the integrity of the input, we use [AEAD] with an -[implementation][AEAD implementation] based on BoringSSL. - -The encrypted templates are wrapped inside JSON files that could be corrupted or -tampered with. Biod does parse and interpret some fields of those JSON files. -That input is [fuzzed]. - -### Sensitive data - -The SBP handles biometric data, see the [Detailed Design](#detailed-design) -section that describes how we keep that data protected from attackers. - -### Attack surface - -#### Libraries - -* Biod uses libbrillo and libchrome -* The SBP firmware is based on the cros_ec code already used in the EC. Two - significant additions: - * Parts of BoringSSL (AES and AES-GCM) ported to cros_ec - * 3rd-party proprietary blob used for matching, see - [Closed source blobs in the SBP](#closed-source-blobs). - -#### Remote attacks - -Neither biod nor the SBP are exposed directly to remote attackers. Since biod -communicates with Chrome over D-Bus, and attacker who had compromised Chrome -could start sending D-Bus commands to biod. - -#### Closed source blobs in the SBP {#closed-source-blobs} - -The enrollment/matching and image capture libraries are provided by a 3rd-party -vendor in binary form. That proprietary blob went through a security audit by a -3rd party auditor (see the auditor’s [report][Security Audit Report]. - -On top of the security audit of the 3rd-party proprietary code, we limit the -attack surface of those libraries by not directly exposing them to user input. -Data (e.g. FP templates) that is fed to those libraries isn’t directly coming -from untrusted user input, it is sanitized by the opensource glue logic and -wrappers. For example, we use AEAD to ensure that the encrypted data that is -deciphered before being passed to the 3rd-party libraries has been generated by -the SBP itself. For more details, see section -[Attack through crafted templates uploaded to the SBP](#template-attack). - -### Implementation robustness - -#### biod (userspace daemon) - -##### Multi-threading/multi-process - -biod uses `base::MessageLoopForIO`, no custom multi-thread or multi-process -implementation. - -##### State machine implementation - -biod has 3 main states: - -* Idle -* Waiting for a match: controlled by the [AuthSession] object -* Enrolling a new fingerprint: controlled by the [EnrollSession] object. - -#### cros_fp (SBP firmware) - -##### Multi-threading/multi-process - -We use the [primitives][EC primitives] of the Chromium OS EC: tasks, hooks, and -deferred functions. - -##### Memory allocation - -Most buffers (e.g. for FP images and templates) are [statically allocated]. The -vendor libraries do require some dynamic memory allocation, we provide -[wrappers functions] that use the [malloc/free memory module for Chrome EC]. - -##### State machine implementation - -There is one main [state machine] that configures the matching/enrollment code -to be ready for a match or to enroll a finger. - -### Cryptography - -See detailed discussion in the ["FP template encryption"](#template-encryption) -section. - -### Metrics {#metrics} - -Metrics related to security that we’re collecting through UMA: - -* `Ash.Login.Lock.AuthMethod.Used.ClamShellMode` to know if FP is used to - authenticate -* `Ash.Login.Lock.AuthMethod.Used.TabletMode` to know if FP is used to - authenticate -* `Fingerprint.Unlock.AuthSuccessful` tracks whether FP authentication was - successful or not -* `Fingerprint.Unlock.AttemptsCountBeforeSuccess` tracks how many attempts it - takes for users to unlock with their fingerprint -* `Fingerprint.UnlockEnabled` tracks whether FP unlocking is enabled or not -* `Fingerprint.Unlock.EnrolledFingerCount` reports the number of fingers that - users have enrolled - -Complete list of metrics collected via UMA: -[New UKM collection review - CrOS FP Unlock] - -### Potential attacks - -#### Enroll a rogue fingerprint - -An attacker with physical access to the device could enroll their own -fingerprint under the victim’s account and use it to unlock the device at-will -in the future. - -* Enrollment UI requires the user password before telling biod to start an - enrollment session, so the attacker would need some form of exploit to - bypass Chrome and trigger the enrollment. We plan to replace this - post-launch with a mechanism similar to [Authentication-Time User Secrets]. - Separate design doc to come. -* Even if it’s not a persistent exploit, a rogue enrolled fingerprint would - persist. -* The victim’s fingerprint data would still be secure. -* The enrollment UI shows how many fingers are enrolled. - -## Privacy Considerations - -### Fingerprint data is kept locally on the device - -The raw fingerprint images themselves never leave the SBP. The fingerprint -templates are kept on the local storage (encrypted both with the `HW_Key` and -the `User_Key`) of the device and not synced to the cloud, encrypted or not. - -### Fingerprint data decryption requires the user password - -The fingerprint templates are stored in a "[cryptohome daemon store folder]" -which is only mounted when the user logs in. To do so, they must have entered -their password. - -### FP matching is not used for login, only unlocking - -Before using their fingerprint to unlock the device the user must have logged -in, typically with the Google Account password. - -### Lock screen will display a FP icon if enabled - -If a user has enabled FP unlocking, a FP icon will be associated to that user on -the lock screen. This potentially lets others know that a user has enabled FP -unlocking. This seems reasonable when the small resulting decrease in privacy is -weighed against the fact that adding an icon greatly improves UX. - -### Metrics collection - -We collect anonymous metrics through [UMA], see section [Metrics](#metrics) for -details. - -### Logs - -Biod, the SBP, and Chrome have logs related to the fingerprint process. -[Privacy fields for Fingerprints] lists the log entries and their privacy -implications. Full [PDD is here]. - -#### Biod - -The log files are in `/var/log/biod/`. - -#### SBP - -The log file is `/var/log/cros_fp.log`. - - - -[2FA]: https://en.wikipedia.org/wiki/Multi-factor_authentication -[AEAD implementation]: https://chromium.googlesource.com/chromiumos/platform/ec/+/aed008f87c3c880edecf7608ab24eaa4bee1bc46/common/fpsensor.c#574 -[AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption -[Arm TrustZone]: https://www.arm.com/products/security-on-arm/trustzone -[Authentication-Time User Secrets]: http://go/authentication-time-user-secrets -[AuthSession]: https://chromium.googlesource.com/chromiumos/platform2/+/eae39a9ad1239f8fbfa8164255578b306ff6ba5c/biod/biometrics_manager.h#96 -[biod D-Bus API]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/system_api/dbus/biod/ -[biod upstart script]: https://chromium.googlesource.com/chromiumos/platform2/+/master/biod/init/biod.conf -[ccd open]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/docs/case_closed_debugging_cr50.md#Open-CCD -[CDD]: https://source.android.com/compatibility/android-cdd#7_3_10_fingerprint_sensor -[Chromium OS EC]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/README.md -[clobber-state]: https://chromium.googlesource.com/chromiumos/platform2/+/962ab1bc481db0cf504b5449eb3a3d5008ea7601/init/clobber_state.cc#475 -[cryptohome daemon store folder]: https://chromium.googlesource.com/chromiumos/docs/+/master/sandboxing.md#securely-mounting-cryptohome-daemon-store-folders -[cryptohome]: https://www.chromium.org/chromium-os/chromiumos-design-docs/protecting-cached-user-data -[Detachable Base Swap Detection]: https://docs.google.com/document/d/1WYdkkSAL_RHVc5mUXnAvBBfAeM7Wj3ABa1dbeTdvm74/edit#heading=h.g74ijelumqop -[Detachable Base Verified Boot Anti-Rollback]: http://go/detachable-base-vboot#heading=h.fimcm174ok3 -[Detachable Base Verified Boot]: http://go/detachable-base-vboot#heading=h.dolfbdpggye6 -[EC primitives]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/README.md#Software-Features -[EnrollSession]: https://chromium.googlesource.com/chromiumos/platform2/+/eae39a9ad1239f8fbfa8164255578b306ff6ba5c/biod/biometrics_manager.h#92 -[fingerprint authentication framework]: https://developer.android.com/about/versions/marshmallow/android-6.0.html#fingerprint-authentication -[fuzzed]: https://chromium.googlesource.com/chromiumos/platform2/+/master/biod/biod_storage_fuzzer.cc -[Global Read-out Protection (RDP) mode Level 1]: https://www.st.com/content/ccc/resource/technical/document/application_note/b4/14/62/81/18/57/48/05/DM00075930.pdf/files/DM00075930.pdf/jcr:content/translations/en.DM00075930.pdf -[HKDF]: https://tools.ietf.org/html/rfc5869 -[Input Key Material (IKM)]: https://en.wikipedia.org/wiki/HKDF -[Intel SGX]: https://software.intel.com/en-us/sgx -[macOS]: https://support.apple.com/en-us/HT207054 -[malloc/free memory module for Chrome EC]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/common/shmalloc.c -[matching algorithm]: https://en.wikipedia.org/wiki/Fingerprint#Algorithms -[mount_encrypted]: https://chromium.googlesource.com/chromiumos/platform2/+/master/cryptohome/mount_encrypted -[New UKM collection review - CrOS FP Unlock]: https://docs.google.com/document/d/1qjDCMcBcrhSeg_uwyEIRsXHKmzUTJahcg6a4YVhkuLo -[Old Design Doc]: https://docs.google.com/document/d/1MdPRmCDkVg1HO9DdbvPT5fDZS2ICg5ys9_ok_K95EEU -[PDD is here]: http://go/cros-fingerprint-pdd -[Privacy fields for Fingerprints]: https://docs.google.com/spreadsheets/d/1jLfnuhfbrImpoxuj92OkAxS_GGrm7QkpQhsUQCkO9ec -[Privacy fields for Fingerprints]: https://docs.google.com/spreadsheets/d/1jLfnuhfbrImpoxuj92OkAxS_GGrm7QkpQhsUQCkO9ec/ -[RM0433]: https://www.st.com/content/ccc/resource/technical/document/reference_manual/group0/c9/a3/76/fa/55/46/45/fa/DM00314099/files/DM00314099.pdf/jcr:content/translations/en.DM00314099.pdf -[sandboxing]: https://chromium.googlesource.com/chromiumos/docs/+/master/sandboxing.md -[seccomp filter]: https://chromium.googlesource.com/chromiumos/platform2/+/master/biod/init/seccomp/biod-seccomp-amd64.policy -[Security Audit Report]: https://drive.google.com/a/google.com/file/d/0B1HHKpeDpzYnMDdocGxwWUhpckpWM0hMU0tPa2ZjdEFnLU53/ -[state machine]: https://chromium.googlesource.com/chromiumos/platform/ec/+/90d177e3f0ae729bea7e24934a3c6ef9f2520d45/common/fpsensor.c#252 -[statically allocated]: https://chromium.googlesource.com/chromiumos/platform/ec/+/90d177e3f0ae729bea7e24934a3c6ef9f2520d45/common/fpsensor.c#57 -[system key]: https://chromium.googlesource.com/chromiumos/platform2/+/23b79133514ac2cd986bce21c398fb6658bda248/cryptohome/mount_encrypted/encryption_key.h#125 -[UMA]: http://go/uma -[Windows]: https://www.microsoft.com/en-us/windows/windows-hello -[wrappers functions]: https://chrome-internal.googlesource.com/chromeos/platform/ec-private/+/9ebb3f10c611afff695f679aaeed1a35551a116b/fpc_sensor_pal.c#52 -[“TPM-seed for Fingerprint MCU”]: http://go/bio_tpm_seed - - - -[Decryption Flowchart]: https://docs.google.com/drawings/d/1-JUWTF7sUTND29BfhDvIudzX_S6g-iwoxG1InPedmVw/export/png -[Encryption Flowchart]: https://docs.google.com/drawings/d/1uUprgLsTUZZ2G2QWRYcRn6zBAh6ejvJagVRD7eZQv-k/export/png -[Fingerprint Architecture]: https://docs.google.com/drawings/d/1DFEdxfDXEtYY3LNOOJFAxVw2A7rKouH98tnb1yiXLAA/export/png - diff --git a/docs/fingerprint/fingerprint-dev-for-partners.md b/docs/fingerprint/fingerprint-dev-for-partners.md deleted file mode 100644 index a5f8b35c99..0000000000 --- a/docs/fingerprint/fingerprint-dev-for-partners.md +++ /dev/null @@ -1,530 +0,0 @@ -# FPMCU Development for Partners - -This document is intended to help partners (sensor vendors, MCU vendors, etc) -that are currently (or interested in) developing fingerprint solutions for -Chromebooks. The document assumes that you're using Linux to do the development; -preferably a recent version of Ubuntu or Debian. Some partners have had success -developing in a VM, but please note that we don't test that configuration. - -See the [FPMCU documentation] for additional development information. - -[TOC] - -## Hardware Required for Standalone Development (no Chromebook) - -The following hardware components can be used to set up a standalone development -environment for FPMCU development (i.e., it does not rely on a Chromebook). -Development for other [EC]s is often done in a similar manner, but some of them -have their own standalone development or evaluation kits that don't require the -use of [servo]. - -You will need an [FPMCU reference board](#fpmcu-board) and a -[servo debugger](#servo). - -### FPMCU board - -The Fingerprint MCU (FPMCU) board has the MCU that handles all -fingerprint-related functionality (matching, encryption, etc). The fingerprint -sensor itself connects to the FPMCU board. - -This FPMCU board is the Bloonchipper Rev 0.1. | ---------------------------------------------- | -![Bloonchipper board] | - -*** note -NOTE: Some FPMCU boards need a rework in order to work properly with -servo. This fix is visible in the green box above. - -See the [Bloonchipper Servo Fix](#bloonchipper-servo-fix) section for more -detail. -*** - -This FPMCU board is the Dartmonkey Rev 0.1. | -------------------------------------------- | -![Dartmonkey board] | - -### Servo - -Servo is a general purpose debug board that connects to a header on the FPMCU -board. Among other things, the servo supplies power to the FPMCU and can be used -to program the FPMCU, interact with the EC console, take power measurements, and -debug a running program. It supports SPI, UART, I2C, as well as JTAG/SWD. - -There are two different servo debugger setups supported, the -[Servo Micro](#servo-micro) and the [Servo V2 + Yoshi](#servo-v2-yoshi). The -servo micro is recommended for its simplicity, but currently lack builtin -JTAG/SWD support for single step debugging. - -| [Servo Micro](#servo-micro) | [ServoV2 + Yoshi](#servo-v2-yoshi) | -| --------------------------- | ----------------------------------------- | -| ![Servo Micro] | ServoV2 ![Servo v2] Yoshi Flex ![Standard Yoshi Flex] | - -*** note -For more information about both servos, see [servo]. -*** - -### Servo Micro - -Unlike the Servo V2, the newer servo micro does not require any adapters to -interface with the FPMCU board. - -As you can see below, one end connects to the FPMCU board and the other connect -to the developer's computer over micro USB. - -![Servo Micro with Bloonchipper] - -*** note -For more information about Servo Micro, see [Servo Micro Info]. -*** - -### Servo V2 + Yoshi - -Servo V2 is the original full featured debugger. It requires a -[Yoshi Flex Cable](#yoshi-flex-cable) to interface with the FPMCU. - -![Servo v2] - -*** note -NOTE: More information on servo can be found in the [servo] documentation. -*** - -#### Yoshi Flex Cable - -The Yoshi Flex cable is used to connect Servo v2 to the FPMCU board. The -standard cable does not work with SWD, but a simple rework can be performed to -support SWD. - -Standard Yoshi Flex | Yoshi Flex Reworked to Support SWD ----------------------- | ------------------------------------- -![Standard Yoshi Flex] | ![Yoshi Flex Reworked to Support SWD] - -Rework steps: - -* Remove R18 and R19 -* Wire from Pin 6 of U21 to right side of R18 -* Wire from Pin 6 of U21 to right side of R19 - -#### Micro USB Cable - -A micro USB cable is needed to connect the the servo v2 board to your host Linux -development machine. - -* [Micro USB Cable] - -#### Servo V2 Hardware Setup - -1. Connect the Yoshi Flex cable to servo, paying attention to the pin - numbering. - - ![Connect Yoshi Flex] ![Another Yoshi Flex image] - -2. Connect the other end of the Yoshi Flex cable to the servo header on the - FPMCU board. - - ![Connect Yoshi Flex to FPMCU board] ![Another image] - - *** note - Newer FPMCU boards require the ribbon cable to connect in the - reverse direction. - *** - -3. Connect the fingerprint sensor to the header on the FPMCU board. - -4. Connect the micro USB cable to servo's `HOST_IN` port. The other end of the - USB cable should be plugged into your host development machine. - - ![Connect USB to Servo] - -5. Optional: Connect SWD Debugger - - If you want to use SWD for debugging, connect your debugger to the `JTAG` - header on servo v2. - - ![Connect SWD Debugger] - -## Software Setup - -### Get the Chromium OS source code - -* First, make sure you [have the prerequisites]. -* Then [get the source]. -* Create and [enter the `chroot`]. - * You can stop after the `enter the chroot` step. - -### Build the [EC] (embedded controller) codebase - -Open **two** terminals and enter the chroot in each: - -```bash -# from a terminal on your machine -(outside chroot) $ cd ~/chromiumos/src - -# enter the chroot (the flag is important) -(outside chroot) $ cros_sdk --no-ns-pid -``` - -*** note -NOTE: More information on servo can be found in the [servo] documentation. -*** - -In one of the terminals, build and start `servod` - -Build and install `servod` in the chroot: - -```bash -(chroot) $ sudo emerge hdctools -``` - -*** note -In all of the following commands, replace `` in the command with -`bloonchipper` or `dartmonkey` depending on the development board you are using. -*** - -Run `servod`: - -```bash -(chroot) $ sudo servod --board= --config _rev0.1.xml -``` - -You should see something like this. Leave it running: - -```bash -2019-04-11 15:21:53,715 - servod - INFO - Start -2019-04-11 15:21:53,765 - servod - INFO - Found servo, vid: 0x18d1 pid: 0x5002 sid: 911416-00789 -2019-04-11 15:21:53,766 - servod - INFO - Found XML overlay for board zerblebarn -2019-04-11 15:21:53,766 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_v2_r1.xml, None, 0) -2019-04-11 15:21:53,767 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_v2_r0.xml, None, 0) -2019-04-11 15:21:53,771 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/common.xml, None, 0) -2019-04-11 15:21:53,772 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/power_tools.xml, None, 0) -2019-04-11 15:21:53,774 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/keyboard.xml, None, 0) -2019-04-11 15:21:53,775 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/uart_common.xml, None, 0) -2019-04-11 15:21:53,777 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/ftdii2c_cmd.xml, None, 0) -2019-04-11 15:21:53,777 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/usb_image_management.xml, None, 0) -2019-04-11 15:21:53,784 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servo_zerblebarn_overlay.xml, None, 0) -2019-04-11 15:21:53,785 - SystemConfig - INFO - Loading XML config (/usr/lib64/python2.7/site-packages/servo/data/servoflex_v2_r0_p50.xml, None, 0) -2019-04-11 15:21:53,792 - Servod - INFO - Initializing interface 1 to ftdi_dummy -2019-04-11 15:21:53,792 - Servod - INFO - Initializing interface 2 to ftdi_i2c -2019-04-11 15:21:53,795 - Servod - INFO - Initializing interface 3 to ftdi_uart -2019-04-11 15:21:53,799 - Servod - INFO - /dev/pts/8 -2019-04-11 15:21:53,799 - Servod - INFO - Initializing interface 4 to ftdi_uart -2019-04-11 15:21:53,802 - Servod - INFO - /dev/pts/9 -2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003 -2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 5 to ftdi_dummy -2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003 -2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 6 to ftdi_dummy -2019-04-11 15:21:53,802 - Servod - INFO - Use the next FTDI part @ pid = 0x5003 -2019-04-11 15:21:53,802 - Servod - INFO - Initializing interface 7 to ftdi_uart -2019-04-11 15:21:53,805 - Servod - INFO - /dev/pts/10 -2019-04-11 15:21:53,805 - Servod - INFO - Use the next FTDI part @ pid = 0x5003 -2019-04-11 15:21:53,805 - Servod - INFO - Initializing interface 8 to ftdi_uart -2019-04-11 15:21:53,808 - Servod - INFO - /dev/pts/11 -2019-04-11 15:21:53,808 - Servod - INFO - Initializing interface 9 to ec3po_uart -2019-04-11 15:21:53,811 - PD/Cr50 - EC3PO Interface - INFO - -------------------- PD/Cr50 console on: /dev/pts/12 -2019-04-11 15:21:53,811 - Servod - INFO - Initializing interface 10 to ec3po_uart -2019-04-11 15:21:53,812 - EC - EC3PO Interface - INFO - -------------------- EC console on: /dev/pts/14 -2019-04-11 15:21:54,316 - Servod - INFO - Initialized i2c_mux to rem -2019-04-11 15:21:54,317 - Servod - INFO - Initialized i2c_mux_en to on -2019-04-11 15:21:54,319 - Servod - INFO - Initialized pch_disable to off -2019-04-11 15:21:54,320 - Servod - INFO - Initialized jtag_buf_on_flex_en to off -2019-04-11 15:21:54,321 - Servod - INFO - Initialized cold_reset to off -2019-04-11 15:21:54,322 - Servod - INFO - Initialized warm_reset to off -2019-04-11 15:21:54,323 - Servod - INFO - Initialized spi1_buf_on_flex_en to off -2019-04-11 15:21:54,324 - Servod - INFO - Initialized spi_hold to off -2019-04-11 15:21:54,326 - Servod - INFO - Initialized pwr_button to release -2019-04-11 15:21:54,327 - Servod - INFO - Initialized lid_open to yes -2019-04-11 15:21:54,328 - Servod - INFO - Initialized spi2_buf_on_flex_en to off -2019-04-11 15:21:54,330 - Servod - INFO - Initialized rec_mode to off -2019-04-11 15:21:54,331 - Servod - INFO - Initialized fw_up to off -2019-04-11 15:21:54,332 - Servod - INFO - Initialized usb_mux_sel1 to dut_sees_usbkey -2019-04-11 15:21:54,333 - Servod - INFO - Initialized prtctl4_pwren to on -2019-04-11 15:21:54,334 - Servod - INFO - Initialized uart3_en to on -2019-04-11 15:21:54,334 - Servod - INFO - Initialized dut_hub_pwren to on -2019-04-11 15:21:54,335 - Servod - INFO - Initialized kbd_en to off -2019-04-11 15:21:54,337 - Servod - INFO - Initialized spi1_vref to pp3300 -2019-04-11 15:21:54,338 - Servod - INFO - Initialized spi2_vref to pp1800 -2019-04-11 15:21:54,339 - Servod - INFO - Initialized uart2_en to on -2019-04-11 15:21:54,340 - Servod - INFO - Initialized uart1_en to on -2019-04-11 15:21:54,341 - Servod - INFO - Initialized jtag_buf_en to off -2019-04-11 15:21:54,342 - Servod - INFO - Initialized fw_wp_en to off -2019-04-11 15:21:54,343 - Servod - INFO - Initialized sd_vref_sel to off -2019-04-11 15:21:54,343 - Servod - INFO - Initialized ec_ec3po_interp_connect to on -2019-04-11 15:21:54,344 - Servod - INFO - Initialized uart3_vref to off -2019-04-11 15:21:54,345 - Servod - INFO - Initialized jtag_vref_sel0 to pp3300 -2019-04-11 15:21:54,346 - Servod - INFO - Initialized jtag_vref_sel1 to pp3300 -2019-04-11 15:21:54,346 - Servod - INFO - Initialized fpmcu_ec3po_interp_connect to on -2019-04-11 15:21:54,349 - ServoDeviceWatchdog - INFO - Watchdog setup for devices: set([(6353, 20482, '911416-00789')]) -2019-04-11 15:21:54,351 - servod - INFO - Listening on localhost port 9999 -``` - -In the other terminal, build and flash the firmware: - -Navigate to the EC source: - -```bash -(chroot) $ cd ../platform/ec -``` - -Build the firmware: - -```bash -(chroot) $ make BOARD= -j -``` - -The resulting file will be in `build//ec.bin` - -Flash the firmware file: - -```bash -(chroot) $ ./util/flash_ec --board= --image=./build//ec.bin -``` - -Connect to the UART pty: - -```bash -(chroot) $ sudo screen $(dut-control raw_fpmcu_uart_pty | cut -d: -f2) -``` - -Press enter key several times (may need to wait up to 20 seconds). Then you will -see a prompt: - -``` -> -``` - -At this point you are connected to the MCU's serial (UART) console. You can list -all of the available console commands with "help": - -``` -> help -``` - -```bash -Known commands: -  chan           fpcapture      hcdebugsherase     fpenroll       history        spixfer        waitms -  flashinfo      fpmatch        hostevent      sysinfo -  flashread      gettime        md             sysjump -  flashwp        gpioget        panicinfo      syslock -  flashwrite     gpioset        reboot         taskinfo -HELP LIST = more info; HELP CMD = help on CMD. -``` - -Start a fingerprint enrollment: - -``` -> fpenroll -``` - -The Bloonchipper reference board has an onboard INA that monitors the voltage -and power draw of the MCU and FP Sensor independently. - -Signal Name | Description -------------- | ------------------------------------- -pp3300_dx_mcu | 3.3V supplying the MCU -pp3300_dx_fp | 3.3V supplying the fingerprint sensor -pp1800_dx_fp | 1.8V supplying the fingerprint sensor - -You can monitor all power and voltages by using the following command: - -```bash -(chroot) $ watch -n0.5 dut-control pp3300_dx_mcu_mv pp3300_dx_fp_mv \ -pp1800_dx_fp_mv pp3300_dx_mcu_mw pp3300_dx_fp_mw pp1800_dx_fp_mw -``` - -*** note -The `_mv` suffix denotes millivolt and `_mw` suffix denotes milliwatt. -*** - -*** note -See [Power Measurement Documentation] for more information. -*** - -### Contributing Changes - -#### Using Gerrit and git - -If you’re not familiar with `git`, Gerrit (code review) and `repo`, here are -some docs to help you get started: - -* [Git and Gerrit Intro for Chromium OS]: Useful to get started as quickly as - possible, but does not explain how `git` works under the hood. -* [Set your editor]: Use your favorite editor when writing `git` commit - messages. -* [Chromium OS Contributing Guide]: Detailed overview of contributing changes - to Chromium OS and the workflow we use. -* [Git: Concepts and Workflow]: Good overview of how `git` actually works. -* [Gerrit: Concepts and Workflow]: Good overview of how Gerrit works; assumes - you understand `git` basics. -* [Life of a patch]: Android workflow, but similar to Chrome OS. - -The Gerrit dashboard that will show your pending reviews (and ones we have for -you): - -* [Public Gerrit] -* [Internal Gerrit] - -#### Registering for a chromium.org *Internal* Account - -If your partnership agreement requires non-public code sharing you will need to -register for an account on the [Internal Gerrit]. Refer to the -[Gerrit Credentials Setup] page for details. Once you register for an internal -account, your contact at Google can make sure you have the necessary permissions -to access the necessary repo. - -## Working with Chromebooks - -Chromebooks have an FPMCU (e.g., Bloonchipper) board attached to the -motherboard. You can use the device to run `ectool` commands and test the -fingerprint sensor from the UI. - -### Developer Mode and Write Protection - -Make sure that your fingerprint-equipped Chrome OS device is in [developer mode] -with a *test* image flashed and [hardware write protection] disabled. Using the -test image will allow you to SSH into the device and disabling hardware write -protection allows you to have full access to flashing the FPMCU firmware. - -See [Installing Chromium] for details on flashing test images and enabling -[developer mode]. - -### Connecting - -In general, most of our development is done by connecting to the DUT (device -under test) via SSH. We usually connect the DUT to ethernet (e.g., via USB-C to -Ethernet converter), but WiFi should also work (assuming corporate firewall -restrictions don’t block SSH port 22). To get the IP address, tap the -battery/time icon in the lower right corner. Then tap on “Ethernet” followed by -the gear icon in the upper right. - -```bash -(chroot) $ ssh root@ -Password: test0000 -``` - -Once you have SSH’ed into the DUT, you should be able to run `ectool` commands. - -**Example**: Capture a "test_reset" image from the sensor and write it to a -[PNM] file (viewable with the ImageMagick `display` command): - -```bash -(device) $ ectool --name=cros_fp fpmode capture test_reset; ectool --name=cros_fp waitevent 5 500; ectool --name=cros_fp fpframe > /tmp/test_reset.pnm -``` - -Alternatively, you can access a shell via the UI on device by pressing -`CTRL+ALT+F2` (third key on top row). Log in with `root` and `test0000`. - -### Flashing FPMCU from DUT - -Copy the firmware to the DUT: - -```bash -(chroot) $ scp ./build/bloonchipper/ec.bin :/tmp/ec.bin -``` - -From the DUT, flash the firmware you copied: - -```bash -(device) $ flash_fp_mcu /tmp/ec.bin -``` - -## Troubleshooting - -### Bloonchipper Servo Fix - -Bloonchipper Rev 0.1 has a known issue with UART and JTAG. Most notably, this -issue causes servo micro to fail to program the FPMCU over UART. - -This issue can be fixed with the following rework steps: - -* Connect servo header pin 13 to pin 18 -* Connect servo header pin 13 to pin 29 - -![Bloonchipper servo fix diagram] - -### Verify that servo and debugger are connected to USB {#servo-connected} - -Check whether servo is enumerating on USB. If you are using a debugger -(Lauterbach, J-Link, etc), also check to make sure it enumerates. Depending on -the debugger being used, it may need to be powered with an external power -supply. - -```bash -(chroot) $ lsusb - -Bus 002 Device 003: ID 0897:0004 Lauterbach # ← This is my Lauterbach (debugger) -Bus 001 Device 013: ID 18d1:5002 Google Inc. # ← This is servo -``` - -### "No servos found" when running servod - -If you get the following message, make sure that -[servo is connected to USB](#servo-connected). You may also want to try -restarting your machine (or VM). - -```bash -(chroot) $ sudo servod --board=bloonchipper -2019-04-12 14:53:42,236 - servod - INFO - Start -2019-04-12 14:53:42,270 - servod - ERROR - No servos found -``` - -### Losing characters in servo UART console - -Make sure that this interface is disabled: - -```bash -(chroot) $ dut-control usbpd_ec3po_interp_connect:off -``` - -### "Sweetberry" board fails to build - -If you're trying to run `make buildall -j` in the EC codebase and the build -fails when trying to build the "sweetberry" board, see this bug: -https://crbug.com/992082. - -### FPMCU console commands - -* Once the console is working you can use `help` to see the commands. -* There should be fingerprint commands that start with `fp` (see `fpsensor.c` - in the [EC] code). - - - -[EC]: https://chromium.googlesource.com/chromiumos/platform/ec -[ectool_servo_spi]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/util/comm-servo-spi.c#15 -[servo]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/README.md -[developer mode]: https://chromium.googlesource.com/chromiumos/docs/+/master/debug_buttons.md#firmware-keyboard-interface -[hardware write protection]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/docs/write_protection.md -[have the prerequisites]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Prerequisites -[get the source]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#get-the-source -[enter the `chroot`]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#building-chromium-os -[Chromium OS Contributing Guide]: https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md -[Servo Micro Info]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/servo_micro.md -[Set your editor]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#Set-your-editor -[Life of a patch]: https://source.android.com/setup/contribute/life-of-a-patch -[Git: Concepts and Workflow]: https://docs.google.com/presentation/d/1IQCRPHEIX-qKo7QFxsD3V62yhyGA9_5YsYXFOiBpgkk/ -[Gerrit: Concepts and Workflow]: https://docs.google.com/presentation/d/1C73UgQdzZDw0gzpaEqIC6SPujZJhqamyqO1XOHjH-uk/ -[Public Gerrit]: https://chromium-review.googlesource.com -[Power Measurement Documentation]: https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/power_measurement.md -[Internal Gerrit]: https://chrome-internal-review.googlesource.com -[Gerrit Credentials Setup]: https://www.chromium.org/chromium-os/developer-guide/gerrit-guide -[Micro USB Cable]: https://www.monoprice.com/product?p_id=9762 -[PNM]: https://en.wikipedia.org/wiki/Netpbm_format -[Git and Gerrit Intro for Chromium OS]: https://chromium.googlesource.com/chromiumos/docs/+/master/git_and_gerrit_intro.md -[Installing Chromium]: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_guide.md#installing-chromium-os-on-your-device -[FPMCU documentation]: ./fingerprint.md - - - -[Servo Micro]: ../images/servo_micro.jpg -[Servo Micro with Bloonchipper]: ../images/servomicro_dragonclaw.jpg -[Servo v2]: ../images/servo_v2.jpg -[Standard Yoshi Flex]: ../images/yoshi_flex.jpg -[Yoshi Flex Reworked to Support SWD]: ../images/yoshi_flex_swd_rework.jpg -[Bloonchipper board]: ../images/dragonclaw_withfix.jpg -[Bloonchipper servo fix diagram]: ../images/dragonclaw_servo_fix.jpg -[Connect USB to Servo]: ../images/servo_v2_with_micro_usb.jpg -[Connect Yoshi Flex]: ../images/servo_v2_with_yoshi_flex.jpg -[Another Yoshi Flex image]: ../images/servo_v2_with_yoshi_flex2.jpg -[Connect Yoshi Flex to FPMCU board]: ../images/dragonclaw_yoshi_flex_header.jpg -[Another image]: ../images/dragonclaw_yoshi_flex_header2.jpg -[Connect SWD Debugger]: ../images/servo_v2_jtag_header.jpg -[Dartmonkey board]: ../images/dartmonkey.jpg diff --git a/docs/fingerprint/fingerprint.md b/docs/fingerprint/fingerprint.md deleted file mode 100644 index b54b79d031..0000000000 --- a/docs/fingerprint/fingerprint.md +++ /dev/null @@ -1,242 +0,0 @@ -# Fingerprint Firmware (FPMCU) - -[TOC] - -*** note -NOTE: The build commands assume you are in the `~/trunk/src/platform/ec` -directory inside the chroot. -*** - -*** note -WARNING: When switching branches in the EC codebase, you probably want to nuke -the `build` directory or at least the board you're working on: `rm -rf -build/` or `make clobber` to prevent compilation errors. -*** - -## Software - -The main source code for fingerprint sensor functionality lives in the -[`common/fpsensor`] directory. - -## Hardware - -The following "boards" (specified by the `BOARD` environment variable when -building the EC code) are for fingerprint: - -* [`nocturne_fp`] aka [`nami_fp`] aka [`dartmonkey`] - * Based on [STM32H743] (Cortex-M7). -* [`hatch_fp`] aka [`bloonchipper`] - * Based on [STM32F412] (Cortex-M4). - * Support for the STM32F412 for the FPMCU is not yet fully complete, - but it is functional enough for testing. - -## Building FPMCU Firmware Locally - -### See `Makefile` target options - -```bash -(chroot) ~/trunk/src/platform/ec $ make help -``` - -### Build - -Replace `` in the command below with the fingerprint MCU that you -are targeting (e.g., `nocturne_fp`, `dartmonkey`, `bloonchipper`). - -```bash -(chroot) ~/trunk/src/platform/ec $ make BOARD= -j -``` - -### Verbose Build output - -Use `V=1` to see the complete compiler output (all flags). - -```bash -(chroot) ~/trunk/src/platform/ec $ make V=1 BOARD=nocturne_fp -j -``` - -## Building all EC firmware (before "repo upload") - -Before uploading a change to Gerrit via `repo upload`, you'll need to build -*all* the boards in the EC codebase to make sure your changes do not break any -others. - -*** note -NOTE: If you forget to do this, do not worry. `repo upload` will warn you and -prevent you from uploading. -*** - -```bash -(chroot) ~/trunk/src/platform/ec $ make buildall -j -``` - -## Build tests - -```bash -(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp tests-nocturne_fp -j -``` - -## Build ectool - -```bash -(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp utils-host -j -``` - -## Build and run the `host_command` fuzz test - -```bash -(chroot) ~/trunk/src/platform/ec $ make BOARD=nocturne_fp run-host_command_fuzz -``` - -## Production Updates - -### `fp_updater.sh` and `bio_fw_updater` - -[`fp_updater.sh`] and [`bio_fw_updater`] are wrappers around [`flashrom`] and -require already-functioning RO firmware running on the FPMCU. It’s meant to be -used in production to update the RW firmware. `fp_updater.sh` was used prior to -M77; `bio_fw_updater` replaces it. - -It's also possible to use the updater to update the RO firmware if you disable -*both* HW and SW write protect, which we use for updating development devices -that do not have write protect enabled (dogfood devices, EVT, etc.) - -In production, only the RW portion of the firmware can be updated (unless the -user disables [hardware write protection]). - -## Factory / RMA / Development Updates - -### `flash_fp_mcu` - -*** note -NOTE: This tool is really just for us to use during development or during the -RMA flow (must go through finalization again in that case). We never update RO -in the field (can’t by design). -*** - -[`flash_fp_mcu`] enables spidev and toggles some GPIOs to put the FPMCU (STM32) -into bootloader mode. At that point it uses [`stm32mon`] to rewrite the entire -flash (both RO and RW). The FPMCU can only be put into bootloader mode when -[hardware write protection] is disabled, which means [`flash_fp_mcu`] can only -be used when [hardware write protection] is disabled. - -### `stm32mon` - -[`stm32mon`] is a tool used to send commands to the STM32 bootloader. We use it -for development (through `flash_fp_mcu`) to erase and flash the entire chip. - -## Keys - -The `RO` section of the fingerprint firmware contains the public portion of the -key used to sign the RW firmware. The RO firmware uses the public key to -validate the signature of the RW firmware before jumping to it. It is not -possible to update the public key stored in the RO firmware once a device has -been shipped (i.e., once [hardware write protection] is enabled). - -Different keys are used to sign the firmware during development and production. -The `dev` key is used for local builds and development and is not private; it -is called `dev_key.pem` and located in the "board" directory for the given -FPMCU (e.g., [`board/nocturne_fp/dev_key.pem`]). After doing a build, the -`ec.bin` in the `build` directory (e.g., `build/nocturne_fp/ec.bin`) will be -signed with the `dev` key. - -The two other types of keys are `premp` and `mp`, which stand for -"pre-mass production" and "mass production", respectively. Both the `premp` and -`mp` keys are only available to the buildbots as part of the official build. -The `premp` is typically used during bringup of new hardware to validate the -signing flow of the buildbots, while the `mp` key is used for PVT and production -devices. - -Switching keys is only possible when the `RO` firmware is not write protected, -since the public portion of the keypair is stored in the `RO` firmware. - -### Resources - -* https://sites.google.com/a/google.com/chromeos/resources/engineering/releng/signer-documentation -* https://sites.google.com/a/google.com/chromeos/paygen---payload -* https://b.corp.google.com/issues/77882970 - -## Signing - -[`futility`] is used to sign EC firmware. There’s a wrapper script around it -for signing called [`sign_official_build.sh`]. - -### Key ID - -The output of `futility show` will show a `Public Key File` and `Signature` -section, each of which have an `ID` field. This ID lets you match the key to the -signature in case there is more than one. -[It’s just a sha1sum of the public key,][vboot_key_id] so it lets you -[uniquely identify the key being used][vb2_public_key]. - -If you have the key (e.g., in PEM format), you can compute the `ID` with the -`futility show` command: - -```bash -(chroot) $ futility show ./path/to/key.pem -``` - -#### Example - -If you are building the `hatch_fp` "board" on your local machine (which signs -the resulting `ec.bin` with the `dev` key, you can check the `ID` with: - -```bash -(chroot)$ futility show board/hatch_fp/dev_key.pem -``` - -``` -Private Key file: board/hatch_fp/dev_key.pem - Key length: 3072 - Key sha1sum: 61382804da86b4156d666cc9a976088f8b647d44 -``` - -```bash -(chroot)$ futility show build/hatch_fp/ec.bin -``` - -``` -Public Key file: build/hatch_fp/ec.bin - Vboot API: 2.1 - Desc: "" - Signature Algorithm: 7 RSA3072EXP3 - Hash Algorithm: 2 SHA256 - Version: 0x00000001 - ID: 61382804da86b4156d666cc9a976088f8b647d44 -Signature: build/hatch_fp/ec.bin - Vboot API: 2.1 - Desc: "" - Signature Algorithm: 7 RSA3072EXP3 - Hash Algorithm: 2 SHA256 - Total size: 0x1b8 (440) - ID: 61382804da86b4156d666cc9a976088f8b647d44 - Data size: 0x2864c (165452) -Signature verification succeeded. -``` - -### Showing Key ID (fingerprint) for running FW - -[Asked on chromeos-chatty-firmware][chatty-firmware-q] -about adding an EC command to show the Key ID (fingerprint) from the RO version. -This would make it a lot easier during both development and testing. - -[`common/fpsensor`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/common/fpsensor/ -[`nocturne_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/nocturne_fp/ -[`nami_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/nami_fp/ -[`hatch_fp`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/hatch_fp/ -[`bloonchipper`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/bloonchipper/ -[`dartmonkey`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/refs/heads/master/board/dartmonkey/ -[hardware write protection]: ../write_protection.md -[`flash_fp_mcu`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/nocturne_fp/flash_fp_mcu -[`stm32mon`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/e1f3f89e7ea7945adddd0c2e6838f5e59856cff2/util/stm32mon.c#14 -[`futility`]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/master/futility/ -[`sign_official_build.sh`]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/master/scripts/image_signing/sign_official_build.sh -[vboot_key_id]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/e7db36856ce418552637d1981c173d22dfe5bf39/firmware/2lib/include/2id.h#5 -[vb2_public_key]: https://chromium.googlesource.com/chromiumos/platform/vboot_reference/+/e7db36856ce418552637d1981c173d22dfe5bf39/firmware/2lib/include/2rsa.h#14 -[chatty-firmware-q]: https://groups.google.com/a/google.com/d/msg/chromeos-chatty-firmware/ZSg423wsFPg/26UbdGwjFQAJ -[`fp_updater.sh`]: http://go/cros-fp-updater-nocturne-source -[`bio_fw_updater`]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/master/biod/tools -[`flashrom`]: https://chromium.googlesource.com/chromiumos/third_party/flashrom/ -[STM32F412]: https://www.st.com/resource/en/reference_manual/dm00180369.pdf -[STM32H743]: https://www.st.com/resource/en/reference_manual/dm00314099.pdf -[`board/nocturne_fp/dev_key.pem`]: https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/nocturne_fp/dev_key.pem diff --git a/docs/low_battery_startup.md b/docs/low_battery_startup.md deleted file mode 100644 index 82f5c8c6ab..0000000000 --- a/docs/low_battery_startup.md +++ /dev/null @@ -1,428 +0,0 @@ -# Configuring the EC for Low-Battery Startup - -Near the bottom of charge, starting up a ChromeOS device can be a tricky -proposition. Several features interact to make it difficult to reliably turn on -the machine without browning out. Over the years, a variety of configuration -options have been written to maximize ChromeOS's compatibility with the basic -user expectation, - -"I plugged it in, therefore it should turn on." - -When creating a new board configuration, this document should aid the engineer -in navigating and choosing correct values for these options. - -The first section describes the various features which interact with each other -to create a complex environment for the EC during boot, especially at a low -state of charge. - -Second, we'll provide some reference configurations which cover many -Chromebooks' use cases. - -Finally, we'll close out with a detailed review of the configuration parameters -which are available. - -## Interacting Features - -### Battery and Charging Circuit - -For the most part, ChromeOS device power systems are much like other laptop -battery power systems. A variable-voltage rail is connected to the battery via -a series of cutoff MOSFETs. Several system power rails derive their power from -the system's variable-voltage rail. Mains power is delivered to the -variable-voltage system rail by a buck/boost charging circuit. Mains power is -itself rectified, isolated, and stepped down by an external power supply. - -During most of the battery charge, the charger operates in current mode, acting -as a constant current source that delivers current to the variable-voltage rail. -Load transients are served by the capacitance on the rail and the battery. By -superposition, load transients during the charge don't necessarily draw current -from the battery, they may just reduce the current flow into the battery. - -References to AC power in the EC codebase are actually references to an external -power supply's DC source. External supplies that are actually USB-PD-speaking -battery packs are indistinguishable from AC/DC adapters as far as the EC is -concerned. Variables and functions which refer to external supplies all refer -to them as 'AC', though. - -### Source Current Negotiation - -A device may draw power from an AC adapter via a few methods. - -#### USB BC1.2 Current Sources - -BC1.2 negotiation is usually managed entirely by an external IC. Once it is -complete, the EC limits itself to 2.4A max. Additionally, the charger may be -configured to switch to an input voltage regulation mode if the input voltage -begins to sag too low. - -Ideally, the input source provides a voltage droop, such that it is not quite -overloaded at the input voltage regulation setpoint of about 4.5V. Thus, 4.5V -serves as a reasonable reference voltage for the charger to use when it is in an -input voltage-regulation mode. - -In effect, the EC limits to both a maximum current of 2.4A and minimum voltage -of 4.5V, for about 12W of power draw from a BC1.2 source. - -See also `driver/bc12/max14637.c:bc12_detect()`. - -#### USB-PD Sources - -High-current power supplies are negotiated via the USB Type C Current Source and -USB Power Delivery specifications (PD). PD sources must support Type-C Current -Source, but the reverse is not true. Both types of current sources are managed -via the PD protocol module in the EC codebase. - -Type-C Current Source capabilities of up to 15W (3A, 5V) are advertised via -analog signaling alone. Via digital communication in the PD protocol, much -higher power states may be negotiated. However, higher power states also -usually run at a higher voltage state as well. Any time the voltage level is -changing, the power sink (the ChromeOS device) must lower its power consumption -during the transient. The standby current level is governed by -`CONFIG_CHARGER_INPUT_CURRENT`. - -PD port partners are capable of both soft and hard resets. Hard resets will -cause a dead-bus state for a brief interval before PD can renegotiate, from -scratch, because it is intended to emulate a cable disconnect. Therefore, a -hard reset without a connected battery will brownout the Chromebook. - -### Locked and Unlocked Firmware - -The Verified Boot implementation normally limits the complexity of the code -which executes in the locked Read-Only firmware package. The consequences for -the EC are: - -- Locked RO EC firmware does not process any digital PD messages at all, it only - recognizes the analog advertisement of USB Current Source (15W max). -- Installation of user-provided firmware is supported, but the write-protect pin - must be cleared to enable it. -- On recent systems, write-protect is cleared by removing the system battery. - -### ChromeOS `powerd` - -The power management daemon provided by ChromeOS displays a "low-power charger" -warning message via the system tray whenever the charger is limited to less than -20W. Therefore, if a USB-PD source is restricted to analog signaling, or a -BC1.2 source is connected, the user gets alerted to the situation. - -Systems that can run on very little power may be rapidly charged with a 15W -charger, while a high power system may require a 40W state or more for a decent -battery charging user experience. Therefore, a board's overlay may override the -warning threshold by replacing `/usr/share/power_manager/usb_min_ac_watts` in -the board's filesystem. - -See also `platform2/power_manager/` source code. - -### Cell Imbalance - -Under normal conditions, the battery pack is equipped with a management IC which -is solely responsible for the safety of the battery, measurement of the state of -charge, and the balance of its cells. Examples include (but are not limited to) -the TI BQ40Z50 and Renesas RAJ240. - -However, after very long periods of rest without a battery charging cycle, the -natural self-discharge rate of each cell will cause them to diverge somewhat -from each other. - -Some IC's can be configured to report a pack total state of charge of zero if -any one cell's voltage is below a certain threshold. However, many do not. -Therefore, after an extended rest period, one cell can be very close to the cell -undervoltage cutoff threshold, even though the pack as a whole is considered to -be at 3% charge or more. - -### Power Profile During Boot - -The power profile during the boot sequence is substantially different than that -seen during typical use. Dynamic voltage and frequency scaling of the AP is -partially governed by the temperature of the processor core. As the processor -gets hotter, it will reduce its maximum core voltage and frequency to settle out -at some maximum design junction temperature for the core. For passively cooled -devices, the profile may also be chosen to limit the external case temperature. - -At startup, the case and core are cold. The bootloaders and kernel are also -optimized to boot as fast as possible for a responsive user experience. So, the -power drawn during the boot is much higher than that seen during typical -productivity and entertainment tasks. - -### Depthcharge Power Verification - -After verification and optional update of the EC's RW firwmare, Depthcharge will -poll the EC to verify that it is allowed to proceed to boot to the kernel. - -It does this by polling via the: -- `EC_CMD_CHARGE_STATE` host command. -- `CHARGE_STATE_CMD_GET_PARAM` subcommand. -- `CS_PARAM_LIMIT_POWER` parameter. - -When the EC returns 0, power draw by the AP is unlimited and depthcharge resumes -the boot. If the EC fails to return 0 in three seconds, depthcharge shuts down. - -See also VbExEcVbootDone() in Depthcharge, and option -`CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW` in the EC. By default, this option -is not set, and the EC immediately allows the boot to proceed. - -## Example Low-Battery Boot Sequences and Configurations - -Most ChromeOS devices power needs will be met by one of the following templates. - -### Low-Power Device - -Low-power devices require 15W or less of power to boot the AP. The battery pack -is robust enough to support the device during brief intervals of PD negotiation -without browning out. - -``` -#define CONFIG_CHARGER_INPUT_CURRENT 512 -#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 1 -``` - -A detailed boot sequence under this configuration, with a low battery and -available AC power via a USB-PD charger: - -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - Battery state of charge > 1% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware queries the charge state limit power flag via EC-host command, - and the EC immediately responds that it is clear. -1. Depthcharge continues the boot. - 1. In parallel with kernel loading and Linux's boot, the EC performs PD - negotiation. Charger power lowers to 2.5W for up to 500ms as the source - transitions from vSafe5V to its highest supported voltage (15V or 20V - are typical). During this transition time some power is drawn from the - battery. - 1. After PD negotiation is complete, the EC raises the charger current - limit to the negotiated limit (45W is typical). - -### Low-Power Device Startup With Marginal Battery Compatibility - -Similar in configuration to the low-power device startup, this system enables -additional options to maximize its compatibility with marginal batteries near -the bottom of charge. The Grunt family is an exemplar. This system will -complete software sync with less than 15W of power, but may require more power -to boot the kernel and get to the login screen. - -``` -/* Limit battery impact during PD voltage changes. */ -#define CONFIG_CHARGER_INPUT_CURRENT 512 - -/* Distrust the battery SOC measurement a bit. */ -#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3 - -/* - * Require PD negotiation to be complete prior to booting Linux, but don't - * care about how much power we negotiate. - */ -#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 15001 - -/* Extra paranoia about imbalanced cells. */ -#define CONFIG_BATTERY_MEASURE_IMBALANCE -``` - -Additionally, in order to take advantage of cell imbalance detection, the system -battery must support per-cell voltage measurement. - -A detailed boot sequence under this configuration, with a low battery and -available AC power: - -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - battery state of charge >= 3% AND cell imbalance < 200 mV - - OR battery state of charge >= 5% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 15.001W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W - for up to 500ms as the source transitions from vSafe5V to its highest - supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit - to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - - -### High-Power Boot Device Startup - -A "high-power device" in this case is one that requires significantly more than -15W of power to boot the AP. These devices may complete software sync at 15W or -less. Very briefly drawing current out of the battery does not cause a -brownout. - -Example configuration: - -``` -#define CONFIG_CHARGER_INPUT_CURRENT 512 -#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3 -#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON 15000 -#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000 -``` - -Where the low-power device specified a threshold that just barely -requires PD negotiation to happen before booting, this device has a definite -minimum power to boot Linux (27W). A detailed boot sequence under this -configuration, with a low battery and available AC power: - -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - battery state of charge >= 3% - - OR charger power greater or equal to 15W (met by Current Source analog - signaling). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 27W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W - for up to 500ms as the source transitions from vSafe5V to its highest - supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit - to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - - -### High-Power SwSync Device Startup - -Like the high-power boot device startup, these devices draw less than 15W during -most of the software sync process, but may briefly exceed 15W during short -intervals of software sync. However, there is substantial risk of brownout -during those intervals unless the battery is charged up a bit first. Therefore, -they strictly require 1% battery capacity to perform software sync. -Additionally, this configuration requires PD negotiation to be complete prior to -performing a no-battery boot. Nami is an exemplar. - - -Example configuration: - -``` -#define CONFIG_CHARGER_INPUT_CURRENT 512 - -#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC 1 -#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT 15000 - -#define CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON 3 -#define CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON 27000 - -#define CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT 3 -#define CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW 27000 -``` - -1. EC ROM bootloader loads and jumps to the EC's read-only firmware image. -1. RO firmware negotiates a 15W state via Current Source analog signaling and - begins charging the battery with it. -1. RO firmware verifies conditions to begin booting the AP: - - Battery state of charge is greater than 1% AND charger power is greater - than 15W (met after a minute or so of charging on analog signaling) - - OR Battery state of charge is greater than 3% - - OR Charger power is greater than 27W (met after PD negotiation in - unlocked RO firmware). -1. AP firmware performs verification of the EC's RW image, upgrades it if - necessary, and sysjumps the EC to it. -1. AP firmware polls the charge state limit power flag via EC-host command for - up to 3 seconds, in 50ms intervals. The EC will return `1` (power limited) - so long as the charger power is < 27W and the battery is less than 3%. - 1. Meanwhile, the EC performs PD negotiation. Charger power lowers to 2.5W - for up to 500ms as the source transitions from vSafe5V to its highest - supported voltage (15V or 20V are typical). - 1. After negotiation is complete, the EC raises the charger current limit - to the negotiated limit (45W is typical). - 1. The EC returns 0 (unlimited) on the next `LIMIT_POWER` request. -1. Depthcharge continues to boot Linux. - - -## Configuration Option Details - -### `CONFIG_CHARGER_INPUT_CURRENT` - -Required. - -The lowest current limit programmed into the charger. This determines both the -default level used on startup, and the value used during the voltage transients -in PD negotiation. - -It should not be higher than 512 mA unless the device ships with a discrete -power supply. Raising this term above 512 mA is contrary to USB-PD. It may be -lowered in order to improve compatibility with marginal BC1.2 chargers. - -### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON` - -Required. - -The minimum battery state of charge to start up the AP, in percent of full -charge. - -#### `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON` - -Default: 15000 (15W) - -The minimum charger power level to start the AP even when the battery is less -than `CHARGER_MIN_BAT_PCT_FOR_POWER_ON`, in milliwatts. - -### `CONFIG_BATTERY_MEASURE_IMBALANCE` - -Optional. Only set this option if one or more batteries shipped with this board -support per-cell battery voltage measurement. - -When enabled, the EC will query the attached battery for its per-cell voltages. -If the cell voltage is excessively imbalanced at a low state of charge, the boot -is inhibited. - -#### `CONFIG_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON` - -Default: 5%. Above this battery state of charge, cell voltage balance is -ignored. - -#### `CONFIG_BATTERY_MAX_IMBALANCE_MV` - -Default: 200 mV. If the difference between the highest and lowest cell exceeds -this value, then the pack is considered to be imbalanced. - -Note that lithium chemistry cells will almost always read similar voltages. It -is only near the top and bottom of charge that the slope of dV/dQ increases -enough for small cell imbalances to be visible as a voltage difference. - -### `CONFIG_CHARGER_LIMIT_POWER_THRESH_CHG_MW` - -Optional. - -The minimum charger power level to allow Depthcharge to start up the kernel, -even when the battery state of charge is less than -`CHARGER_LIMIT_POWER_THRESH_BAT_PCT`, in milliwatts. - -When this term is `#undef`ined (the default), kernel startup is immediately -allowed. - -#### `CONFIG_CHARGER_LIMIT_POWER_THRESH_BAT_PCT` - -Optional. - -The minimum battery state of charge to allow Depthcharge to start up the kernel. -When using this feature, start with `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON` - -### `CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC` - -Optional. - -Similar to `MIN_BAT_PCT_FOR_POWER_ON`, but used to define a secondary threshold -for this feature. - -#### `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON_WITH_BATT` - -Optional. - -Similar to `CONFIG_CHARGER_MIN_POWER_MW_FOR_POWER_ON`, this is the minimum -charger power needed to boot even when the battery is less than -`CONFIG_CHARGER_MIN_BAT_PCT_FOR_POWER_ON_WITH_AC` - diff --git a/docs/sitemap.md b/docs/sitemap.md index 22e7a959f2..e975d7c7bf 100644 --- a/docs/sitemap.md +++ b/docs/sitemap.md @@ -13,23 +13,11 @@ * [Google Security Chip Case Closed Debugging](./case_closed_debugging_cr50.md) * [Tutorials](./ccd_howtos.md) -## Fingerprint MCU (FPMCU) - -* [Fingerprint MCU (FPMCU)](./fingerprint/fingerprint.md) -* [FPMCU Development for Partners](./fingerprint/fingerprint-dev-for-partners.md) -* [Fingerprint Authentication Design Doc](./fingerprint/fingerprint-authentication-design-doc.md) - ## Updaters * [USB Updater](./usb_updater.md) -## USB - -* [USB-C Power Delivery and Alternate Modes](./usb-c.md) -* [USB-A and USB-C Policies for Sourcing Power](./usb_power.md) - ## Miscellaneous -* [Low Battery Startup](./low_battery_startup.md) * [I2C tracing via console commands](./i2c-debugging.md) * [Application Processor to EC communication](./ap-ec-comm.md) diff --git a/docs/usb-c.md b/docs/usb-c.md deleted file mode 100644 index d6327d6dc7..0000000000 --- a/docs/usb-c.md +++ /dev/null @@ -1,222 +0,0 @@ -# EC Implementation of USB-C Power Delivery and Alternate Modes - -USB-C PD requires a complex state machine as USB-C PD can operate in many -different modes. This includes but isn't limited to: - -* Negotiated power contracts. Either side of the cable can source or sink - power up to 100W (if supported by device). -* Reversed cable mode. This requires a mux to switch the signals before - getting to the SoC (or AP). -* Debug accessory mode, e.g. - [Case Closed Debugging (CCD)](case_closed_debugging_cr50.md) -* Multiple uses for the 4 differential pair signals including - * USB SuperSpeed mode (up to 4 lanes for USB data) - * DisplayPort Alternate Mode (up to 4 lanes for DisplayPort data) - * Dock Mode (2 lanes for USB data, and 2 lanes for DisplayPort) - * Audio Accessory mode. (1 lane is used for L and R analog audio signal) - -For a more complete list of USB-C Power Delivery features, see the -[USB-C PD spec][USB PD Spec Id]. - -This document covers various touch points to consider for USB-C PD and Alternate -Modes in the EC codebase. - -[TOC] - -## Glossary - -* PD {#pd} - * Power Delivery. Protocol over USB-C connector that allows up to 100W of - power. Not supported on USB-A or USB-B connectors. A good overview of - USB PD is found in the [Introduction to USB Power Delivery] application - note. -* TCPC {#tcpc} - * Type-C Port Controller. Typically a separate IC connected through I2C, - sometimes embedded within the EC as a hardware sub module. The TCPC - interprets physical layer signals on CC lines and Vbus, and sends that - information to the TCPM to decide what action to take. In older designs, - there was a separate EC (running this codebase) that acted as the TCPC - that communicated with the main EC (also running this codebase), which - acted as the TCPM. More info in the official - [TCPC spec][USB TCPM Spec Id]. -* TCPM {#tcpm} - * Type-C Port Manager. Manages the state of the USB-C connection. Makes - decisions about what state to transition to. This is the code running on - the EC itself. -* PE {#pe} - * Policy Engine. According to the [TypeC spec][USB TC Spec Id], the policy - engine is the state machine that decides how the USB-C connection - progresses through different states and which USB-C PD features are - available, such as Try.SRC -* TC {#tc} - * Type-C physical layer. -* PPC {#ppc} - * Power Path Controller. An optional, separate IC that isolates various - USB-C signals from each other and the rest of the board. This IC should - prevent shorts and over current/voltage scenarios for Vbus. Some PPCs - will protect signals other than Vbus as well. -* SSMUX {#ssmux} - * SuperSpeed Mux. This is typically the same IC as the TCPC; it enables - the mirrored orientation of the USB-C cable to go to the correct pins on - SoC. Also, allows the SuperSpeed signal to be used for different - purposes, such as USB data or DisplayPort. -* SVDM {#svdm} - * Structured Vendor Defined Messages are a class of [USB PD](#pd) messages - to enable non-power related communication between port partners. SVDMs - are used to negotiate and set the display port mode on a USB-C - connection. -* DRP {#drp} - * Dual Role Power Port. A USB-C port that can act as either a power Source - or power Sink. -* UFP {#ufp} - * Upstream Facing Port. The USB data role that is typical for a peripheral - (e.g. HID keyboard). -* DFP {#dfp} - * Downstream Facing Port. The USB Data role that is typical for a host - machine (e.g. device running ChromeOS). - -* E-Mark {#emark} - * Electronically marked cable. A USB-C cable that contains an embedded - chip in the cable, used to identify the capabilities of the cable. - -* VCONN {#vconn} - * Connector Voltage. A dedicated power supply rail for [E-Mark](#emark) - cables and other accessory functions (such as display dongles, and - docks). VCONN re-uses one of the CC1/CC2 signals to provide 5 volt, 1 - watt, of power. - -## Different PD stacks - -Right now platform/ec has two different implementations of USB-C PD stack. - -1. The older implementation is mainly contained within - [`usb_pd_protocol.c`](../common/usb_pd_protocol.c) and - [`usb_pd_policy.c`](../common/usb_pd_policy.c) -2. The newer implementation is found under [`common/usbc`](../common/usbc) and - is broken up into multiple different files and state machines - * Policy engine state machine files, `usb_pe_*_sm.c`. - * Protocol engine state machine file, `usb_prl_*_sm.c`. - * State machine framework file, `usb_sm.c`. - * Type-C physical layer state machine files, `usb_tc_*_sm.c`. - * USB-C PD Task file, `usbc_task.c`. - -The older implementation supports firmware for device types other than -Chromebooks. For example, the older stack supports the Zinger, which is the -USB-C charging device that shipped with Samus, the Google Chromebook Pixel 2. -The Zinger implements the charger only side of the USB PD protocol. - -To use the newer USB-C PD stack implementation, see `CONFIG_USB_SM_FRAMEWORK` -description in [config.h][config header link]. - -The newer implementation only supports Chromebooks at the moment. There are -multiple policy engine definitions to choose from depending on the different -USB-C features the Chromebook should support. As of now, you must choose one and -only one policy engine state machine implementation. The policy engine mostly -defines what PD features (e.g. Try.SRC) are implemented on the Chromebook. - -## Implementation Considerations - -In both older and newer implementations, the following details apply: - -* For each USB-C port, there must be two tasks: `PD_C#` and `PD_INT_C#`, where - `#` is the port number starting from `0`. - * The `PD_C#` task runs the state machine (old or new) for the port and - communicates with the TCPC, MUX, and PPC. This task needs a large task - stack. - * The `PD_INT_C#` tasks run at a higher priority than the state machine - task, and its sole job is to receive interrupts from the TCPC as quickly - as possible then send appropriate messages to other tasks (including - `PD_C#`). This task shouldn't need much stack space, but the i2c - recovery code requires a decent amount of stack space so it ends up - needing a fair amount too. -* Saving PD state between EC jumps - * PD communication is disabled in locked RO images (normal state for - customer devices). When the jump from RO to RW happens relatively - quickly (e.g. there is not a long memory training step), then there - aren't many problems when RW takes over and negotiates higher PD - contracts. - * To support factory use cases that don't have a battery (and are - therefore unlocked), PD communication is enabled in unlocked RO. This - allows systems without software sync enabled to get a higher power - contract than 15W in RO. - * We save and restore PD state between RO -> RW and RW -> RO jump to allow - us to maintain a higher negotiated power through the full jump and - re-initialization process. For example, for each port we save the power - role, data role, and Vconn sourcing state in battery-backed or - non-volatile RAM. This allows the firmware image that is initializing to - restore an existing SNK contract (Chromebook as SNK) without cutting - power. We don't cut the power from the external supplier because we - issue a SoftReset (leaves Vbus intact) instead of a HardReset (drops - Vbus) in this contract resume case. - * Both use cases where we actually are able to restore the PD contract - require an unlocked RO (e.g. factory) otherwise RO cannot communicate - via PD and will drop the higher PD contract (by applying Rp/Rp on the CC - lines temporarily) - * The RO->RW use case is for an unlocked (e.g. factory) device that - negotiated power and we want to keep that contract after we jump to - RW in the normal software sync boot process. This is especially - useful when there is no battery and Vbus is our only power source. - * The RW->RO use case happens when we are performing auxiliary FW - upgrades during software sync and BIOS instructs the EC to jump back - to RO. We'll also try to maintain contracts over an EC reset when - unlocked. - -## Configuration - -There are many `CONFIG_*` options and driver structs that are needed in the -board.h and board.c implementation. - -### TCPC Config - -The `tcpc_config` array of `tcpc_config_t` structs defined in `board.c` (or -baseboard equivalent) should be defined for every board. The index in the -`tcpc_config` array corresponds to the USB-C port number. This struct should -point to the specific TCPC driver that corresponds to the TCPC that is being -used on that port. The i2c port and address for the TCPC are also specified -here. - -### SSMUX Config - -The `usb_muxes` array of `usb_mux` structs defined in `board.c` (or baseboard -equivalent) should be defined for every board. Normally the standard -`tcpci_tcpm_usb_mux_driver` driver works, especially if TCPC and MUX are the -same IC. - -If the signal strength for the high-speed data lines needs to be tuned for a -specific hardware layout, the `board_init` field on the `usb_mux` is called -every time the mux is woken up from a low power state and should be used for -setting custom board tuning parameters. - -### PPC Config - -Some boards have an additional IC that sits between the physical USB-C connector -and the rest of the board. The PPC IC gates whether the Vbus line is an input or -output signal, based on i2c settings or gpio pins. A PPC also typically provides -over voltage and over current protection on multiple USB-C pins. - -The `ppc_chips` array of `ppc_config_t` structs defined in `board.c` (or -baseboard equivalent) sets the appropriate driver and i2c port/address for the -PPC IC. - -### Useful Config Options - -Many USB-C policies and features are gated by various `CONFIG_*` options that -should be defined in `board.h` (or baseboard equivalent). - -Most USB-C options will start with `CONFIG_USB_PD_` or `CONFIG_USBC_`. For their -full descriptions see [config.h][config header link] - -## Interactions with other tasks - -TODO(https://crbug.com/974302): mention `USB_CHG_P#` and `CHARGER` - -## Upgrading FW for TCPCs - -TODO(https://crbug.com/974302): Mention how this works even though it is in depthcharge. -Probing now. Need new driver in depthcharge - -[USB PD Spec Id]: https://www.usb.org/document-library/usb-power-delivery -[Introduction to USB Power Delivery]: https://www.microchip.com/wwwAppNotes/AppNotes.aspx?appnote=en575003 -[USB TCPM Spec Id]: https://www.usb.org/document-library/usb-type-ctm-port-controller-interface-specification -[USB TC Spec Id]: https://www.usb.org/document-library/usb-type-ctm-cable-and-connector-specification-revision-14-march-29-2019 -[config header link]: ../include/config.h diff --git a/docs/usb_power.md b/docs/usb_power.md deleted file mode 100644 index e066a7bba6..0000000000 --- a/docs/usb_power.md +++ /dev/null @@ -1,250 +0,0 @@ -# USB Power Considerations - -Users want to be able to charge external devices using their Chromebook USB -ports, e.g. charge a phone from their Chromebook. We want to provide a fast -charging experience to end-users, so we prefer to offer high power charging when -possible. - -[TOC] - -## Summary of Design Requirements - -For explanations of calculations see rest of doc. - -### Total System Power - -Total current needed for external USB devices at 5V: - -``` -((Number of Type-C Ports) * (1800mA)) + 1500mA + -((Number of Type-A Ports) * (900mA)) + 600mA§ -``` - -§ The additional 600mA can be omitted if BC1.2 is not supported for Type-A - -### Daughter Board Considerations - -If a daughter board has 1 Type-A (supporting BC 1.2) and 1 Type-C, the max -potential current load at 5V is `Type-A Vbus (1500mA) + Type-C Vbus (3000mA) + -Type-C Vconn (300mA) = 4800mA` - -* The DB ribbon cables need to be able to carry enough current to supply 24W - (4.8A * 5V) of power to the DB. - * This may be on a single or multiple power rails depending on hardware - design. -* The ground path on the ribbon cable from the DB also needs to be able to - carry enough current to match the power rails. - -## USB Type-A Ports - -For Type-A ports, the [BC 1.2 Specification] adds higher power modes on top of -the [USB 3.2 Specification]. While BC 1.2 support isn't required, it is -preferred, as it allows end-users to charge their devices more quickly. - -[BC 1.2 Specification] defines multiple modes of operation including, but not -limited to: - -* CDP - Charging Downstream Port - * Allows USB Data. Provides guaranteed 1.5A @ 5V power. - * ChromeOS device can act as a CDP. -* SDP - Standard Downstream Port - * Allows USB Data. Provides guaranteed current defined by USB - Specifications - * For USB3, provides guaranteed current of 0.9A @ 5V. - * For USB2, provides guaranteed current of 0.5A @ 5V. - * ChromeOS device can act as a SDP. -* DCP - Dedicated Charging Port - * No USB Data. Provides max of 1.5A @ 5V power. - * ChromeOS device **will not** act as a DCP. - -For detection logic of each mode (e.g. on the D+ and D- pins) and nuance of -power/current power requirements, see full [BC 1.2 Specification]. - -Without BC 1.2 support, the max power requirements match that of a Standard -Downstream Port (SDP) as defined by various specification (e.g. -[USB 3.2 Specification]). - -### ChromeOS as Source - Policy for Type-A - -If BC 1.2 is supported on a ChromeOS device, then the first Type-A port in use -will act as a CDP, providing a maximum current of 1.5A while also enabling USB -data. All other Type-A ports will only be SDP, providing a maximum current of -900mA. - -Note that the CDP Type-A port allocation is dynamic; the first Type-A port to -draw more than 900mA gets to be the CDP, with a maximum current of 1.5A. Then -all other Type-A ports get downgraded to the lower, 900mA current limit (i.e. -SDP) while the first Type-A port maintains a current draw of more than 900mA. In -practice, this means that the first Type-A device plugged in gets to consume -1.5A and any Type-A device inserted after that will only get 900mA. - -Once the Type-A device drawing 1.5A stops pulling more than 900mA or is -physically removed, then the extra 600mA (as well as CDP advertisement) becomes -available to any Type-A port. In practice, Type-A devices only determine current -limits when they are first inserted, so any Type-A device that is still plugged -in when the 1.5A device is removed will not notice that it can pull more -current. This means that the first Type-A device **inserted** after removing the -original 1.5A device gets access to 1.5A. - -The allocation of the one CDP Type-A port is unaffected by user interaction with -Type-C ports. Once a Type-A port has been claimed as CDP, inserting a Type-C -device will not revoke the CDP status of the Type-A port. - -For example, the below sequence of events illustrates the above Type-A policy if -BC 1.2 is supported: - -1. Insert Type-A phone first - * Since no other Type-A port is currently supplying more than 900mA, this - port can supply 1.5A as the CDP. - * Phone pulls 1.5A; other Type-A ports are now marked as SDPs limiting - current to 900mA, each. - * Current state: `phone @ 1.5A`. -2. Insert Type-A mouse second - * Mouse is only allowed 900mA since port is SDP. - * Current state: `phone @ 1.5A` and `mouse @ 900mA`. -3. Remove phone - * High-current port status is relinquished. Now first Type-A port to draw - more than 900mA will claim the one high-current port status (as the - CDP). - * Mouse does not realize that more power is available since most Type-A - devices only determine their current limits upon connection. - * Current state: `mouse @ 900ma`. -4. Insert Type-A battery pack - * Since no other Type-A port is currently supplying more than 900mA, this - port can supply 1.5A as the CDP. - * Battery pack pulls 1.5A; other Type-A ports are now marked as SDPs - limiting current to 900mA, each. - * Current state: `mouse @ 900ma` and `battery pack @ 1.5A`. - -The total current needed for all Type-A ports at 5V is: - -``` -if (BC1.2_Supported) - (# Type-A Ports)*(900mA) + 600mA -else - (# Type-A Ports)*(900mA) -``` - -## USB Type-C Ports - -USB Type-C allows for dynamic negotiation of high power contracts; this is -accomplished through varying CC resistors and/or USB-C Power Delivery (PD). More -in-depth information can be found in the [USB Type-C Specification] \(section -4.5.2.3) and the [USB PD Specification]. CC resistor contracts can range from -500mA/5V to 3A/5V, while PD contracts can range from 0mA/3.3V to 5A/20V. - -### ChromeOS as Source - Policy for Type-C - -ChromeOS devices currently source power to external USB devices at 5V with a -typical current of 1.5A for each Type-C port. In certain scenarios, a single -Type-C port can source up to 3A @ 5V. - -ChromeOS prefers that the first PD-capable Type-C device **that claims 3A** -should get 3A guaranteed at 5V. Once a PD-capable Type-C device has claimed 3A, -then other PD-capable Type-C devices will only be offered a maximum of 1.5A. - -If there are no PD-capable Type-C devices claiming 3A, then the first non-PD -device will be given 3A until a PD-capable device **that claims 3A** is -inserted. - -The 3A is only offered after a minimum delay of 200 ms following the initial -connection. One main reason for this delay is to protect against non-PD capabale -devices that only sample the CC resistors once at initial connection from -continuing to consume 3A after we downgrade the CC resistors to 1.5A at a later -point in the future. The motivation for this is that any non-PD device that -notices that it can draw more current from a CC resistor change that happens 200 -ms after the initial connection will also notice a CC resistor change if we -downgrade the CC resistors to a lower current advertisement. We want consistent -behavior across non-PD capable devices and PD-capable devices, so we will only -offer the additional 1.5A to PD ports after the same delay. - -When a device that is currently claiming 3A is removed or proactively reduces -its power contract to 1.5A or less, then the next oldest PD-capable device is -offered 3A in order. If no PD-capable devices claims 3A, then the oldest non-PD -capable device is given 3A through a CC resistor change. - -Inserting a Type-A device does not affect the power assignment for Type-C ports; -only Type-C devices affect the power of Type-C ports. - -For example, the below sequence of events illustrates the above Type-C policy: - -1. A non-PD capable Type-C keyboard is inserted first - * Keyboard will be offered 1.5A initially - * Current state: `keyboard @ 1.5A`. -2. More than 200ms pass. - * Since there are no other PD-capable devices and this is the first - device, offer this device 3A via CC resistor change. - * Current state: `keyboard @ 3A`. -3. A non-PD capable Type-C mouse is inserted second - * It will be offered 1.5A since there is already another non-PD device - claiming 3A. - * Current state: `keyboard @ 3A` and `mouse @ 1.5A`. -4. A PD-capable Type-C dock is inserted third - * Initially negotiate for 1.5A, then wait 200ms after negotiating. - * Since this is the first PD device, we offer it 3A after 200ms from - initial power negotiation. - * Dock does not want high power from Chromebook; dock continues to selects - 1.5A. - * Keyboard gets to maintain higher 3A current supply. - * Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A`. -5. A PD-capable Type-C phone is inserted fourth - * Phone is initially offered 1.5A. - * Since there isn't an existing PD-capable device claiming 3A, the phone - is offered 3A after waiting the 200ms delay from initial negotiation. - * The phone wants high power; phone selects 3A. - * Since PD devices are preferred for 3A, the non-PD keyboard will be - downgraded from 3A to 1.5A via a CC resistor change. - * Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A` - and `phone @ 3A`. -6. A PD-capable Type-C tablet is inserted fifth - * Since there is already a PD-capable device claiming 3A, the tablet is - only offered 1.5A. - * Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A` - and `phone @ 3A` and `tablet @ 1.5A`. -7. The PD-capable phone is done charging so it downgrades its power contract to - 1.5A without any user interaction - * The next oldest PD-capable device is offered 3A in order: dock then - phone then tablet. - * The dock and phone continue to select 1.5A, then the tablet takes 3A. - * Current state: `keyboard @ 1.5A` and `mouse @ 1.5A` and `dock @ 1.5A` - and `phone @ 1.5A` and `tablet @ 3A`. -8. The PD-capable tablet is removed - * The next oldest PD-capable device is offered 3A. If there are no - PD-capable devices claiming 3A, then the oldest non-PD capable device is - given 3A. - * The dock and phone continue to select 1.5A, so keyboard is given 3A via - CC resistor change. - * Current state: `keyboard @ 3A` and `mouse @ 1.5A` and `dock @ 1.5A` and - `phone @ 1.5A`. -9. The non-PD capable keyboard is removed - * The next oldest PD-capable device is offered 3A. If there are no - PD-capable devices claiming 3A, then the next oldest non-PD capable - device is given 3A. - * The dock and phone continue to select 1.5A, so mouse is given 3A via CC - resistor change. - * Current state: `mouse @ 3A` and `dock @ 1.5A` and `phone @ 1.5A`. -10. The non-PD capable mouse is removed - * The dock and phone continue to select 1.5A. - * Current state: `dock @ 1.5A` and `phone @ 1.5A`. - -Note: Not all released Chromebooks implement the above policy due to -pre-existing hardware design constraints. - -Type-C ports also need to provide an additional 300mA @ 5V (1.5W) for Vconn on -every port. Note: the 1.5W for Vconn may also be supplied at other voltages, -such as 455mA @ 3.3V instead. - -The total current needed for all Type-C ports at 5V is: - -``` -((Number of Type-C Ports) * (1500mA + 300mA)) + 1500mA -``` - -The total maximum current needed for a single Type-C port at 5V is `(3000mA + -300mA) = 3.3A`. This max current for a single port is especially relevant for -sizing the daughter board ribbon cable appropriately. - -[BC 1.2 Specification]: -[USB 3.2 Specification]: -[USB PD Specification]: https://www.usb.org/document-library/usb-power-delivery -[USB Type-C Specification]: https://www.usb.org/document-library/usb-type-cr-cable-and-connector-specification-revision-14-march-29-2019 -- cgit v1.2.1