diff options
| -rw-r--r-- | docs/zephyr/zephyr_cbi.md | 60 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_eeprom.md | 90 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_fw_config.md | 78 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_new_board_checklist.md | 3 | ||||
| -rw-r--r-- | docs/zephyr/zephyr_ssfc.md | 104 | ||||
| -rw-r--r-- | zephyr/Kconfig | 49 | ||||
| -rw-r--r-- | zephyr/Kconfig.cbi | 51 |
7 files changed, 344 insertions, 91 deletions
diff --git a/docs/zephyr/zephyr_cbi.md b/docs/zephyr/zephyr_cbi.md new file mode 100644 index 0000000000..7d2f454865 --- /dev/null +++ b/docs/zephyr/zephyr_cbi.md @@ -0,0 +1,60 @@ +# Zephyr CrOS Board Information (CBI) Configuration + +[TOC] + +## Overview + +CrOS Board Info [`CBI`] is used to store static board information, +such as BOARD_VERSION, SKU_ID and configuration information. With [`CBI`], +the information is either hard coded as GPIO values or is stored in a +writable [`EEPROM`] chip, so we can provision the correct SKU at RMA time. + +Kconfig has a CONFIG_PLATFORM_EC_CBI_STORAGE_TYPE choice that lets the +user select GPIOs or an EEPROM as the source of [`CBI`] data. + +If your board uses GPIOs to hard code [`CBI`], then +`CONFIG_PLATFORM_EC_CBI_GPIO` must be selected and the [`CBI`] data will be +emulated and only the BOARD_VERSION and SKU_ID [`CBI`] fields are available. + +If your board includes an [`EEPROM`] to store [`CBI`], then +`CONFIG_PLATFORM_EC_CBI_EEPROM` must be selected and configured. + +[`EEPROM`] [`CBI`] includes two additional pieces of firmware relevant +configuration information that are programmed during manufacturing. + +1) The Firmware Configuration [`FW_CONFIG`] stores information +specifically for the firmware, such as whether the device has a backlit +keyboard. One can view [`FW_CONFIG`] as the firmware characteristic of a +SKU, so a SKU only maps to a single [`FW_CONFIG`], but different SKUs can +map to the same [`FW_CONFIG`]. +2) The Second Source Factory Cache [`SSFC`] also stores information about +the device for the firmware to read. The [`SSFC`] describes later decisions +for a board to indicate alternate second sourced hardware stuffing which +can be used by the EC to know which drivers to load. + +The difference between [`SSFC`] and [`FW_CONFIG`] is that [`SSFC`] doesn’t +affect SKU. This prevents SKU explosion when a device has many second +source components. + +If a Second Source Component is probeable, this should be stored in +[`SSFC`], which avoids creating a new SKU. If it is not probeable, +it must be added to [`FW_CONFIG`]. + +## Kconfig Options + +Refer to [`Kconfig.cbi`] for all the Kconfig options that control [`CBI`] +behavior. + +## Testing and Debugging + +The [`ectool cbi`] command can be run from the kernel to get/set [`FW_CONFIG`] +and [`SSFC`] values. The console has a "cbi" command that can be used to do +the same thing from the EC console. + + +[`CBI`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md +[`ectool cbi`]: ./zephyr_cbi.md#testing-and-debugging +[`EEPROM`]: ./zephyr_eeprom.md +[`FW_CONFIG`]: ./zephyr_fw_config.md +[`SSFC`]: ./zephyr_ssfc.md +[`Kconfig.cbi`]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.cbi diff --git a/docs/zephyr/zephyr_eeprom.md b/docs/zephyr/zephyr_eeprom.md new file mode 100644 index 0000000000..f18669fd75 --- /dev/null +++ b/docs/zephyr/zephyr_eeprom.md @@ -0,0 +1,90 @@ +# Zephyr CBI EEPROM Configuration. + +[TOC] + +## Overview + +Zephyr `EEPROM` [`CBI Configuration`] + +Note: Since the `EEPROM` uses an [`I2C`] interface that must be +configured and working before enabling [`CBI`]. + +## Kconfig Options + +The CrOS Board Information [`CBI`] feature is enabled with the +CONFIG_PLATFORM_EC_CBI_EEPROM Kconfig, as defined in the [`CBI Configuration`]. + +The specific `EEPROM` also needs to be enabled. For example, the Atmel AT24 +would need the following enabled. + +Kconfig Option | Enabled state | Documentation +:------------------------------ | :-----------: | :------------ +`CONFIG_EEPROM` | y | Enabled EEPROM +`CONFIG_EEPROM_AT24` | y | Enable Atmel AT24 + +Device tree is used to define and specify the `EEPROM` device. + +## Devicetree Nodes + +The `EEPROM` device tree nodes are defined for each type of device +YAML bindings that are specific to that particular `EEPROM`. The standard +fashion of defining that `EEPROM` is used with one exception, the `EEPROM` +node must have the nodelabel `cbi_eeprom`. Including the `cbi_eeprom` +nodelabel in the Device Tree will include the cbi_eeprom driver. + +An example definition of the Atmel AT24 is: +``` + &i2c0_0 { + label = "I2C_EEPROM"; + clock-frequency = <I2C_BITRATE_FAST>; + + cbi_eeprom: eeprom@50 { + compatible = "atmel,at24"; + reg = <0x50>; + label = "EEPROM_CBI"; + size = <2048>; + pagesize = <16>; + address-width = <8>; + timeout = <5>; + }; + }; +``` + +Configuring the [`CBI`] Write Protect Signal is also necessary. +The current requirement is that you define an alias node called +"gpio-cbi-wp" that points to the GPIO used as the write protect. + +Note that the "wp-gpios" property should not be used. +"wp-gpios" - Specifies the GPIO output signal from the SoC connected +to the `EEPROM` write protect pin. Zephyr uses this to automatically +control write protection during write and erase operations. +On Chromebooks, the write protect signal is controlled by the Google +Security Chip. gpio-cbi-wb specifies the GPIO input signal to the SoC, +used by the EC application to monitor the write protect state. + +An example of configuring this is: +``` +/ { + aliases { + gpio-cbi-wp = &gpio_cbi_wp; + }; + named-gpios { + gpio_cbi_wp: ec_cbi_wp { + gpios = <&gpio8 1 GPIO_OUT_LOW>; + }; + }; +}; +``` + +## Threads + +No threads used in this feature. + +## Testing and Debugging + +Also the [`I2C bus scan`] can be used to verify the EEPROM device can be accessed. + + +[`CBI`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md +[`CBI Configuration`]: ./zephyr_cbi.md +[`I2C bus scan`]: ./zephyr_i2c.md#Shell-Command_i2c diff --git a/docs/zephyr/zephyr_fw_config.md b/docs/zephyr/zephyr_fw_config.md index abe66addde..94c22a031b 100644 --- a/docs/zephyr/zephyr_fw_config.md +++ b/docs/zephyr/zephyr_fw_config.md @@ -1,28 +1,21 @@ -# Zephyr FW_CONFIG configuration and use. +# Zephyr CBI FW_CONFIG Configuration and Use. [TOC] ## Overview -Zephyr CBI FW_CONFIG configuration +Zephyr [`FW_CONFIG`] [`CBI Configuration`] ## Kconfig Options -The CBI [Cross Board Info](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md) -contains a variety of fields that the EC retrieves from an EEPROM. +The CrOS Board Information [`CBI`] feature is enabled with the +CONFIG_PLATFORM_EC_CBI_EEPROM Kconfig, as defined in the [`CBI Configuration`]. -The CBI feature is enabled using: - -Kconfig Option | Default | Documentation -:--------------------------------| :-----: | :------------ -`CONFIG_PLATFORM_EC_CBI_EEPROM` | n | [zephyr/Kconfig](../zephyr/Kconfig) - -One of the CBI elements is the -[`FW_CONFIG`](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/firmware_config.md) -field. +One of the [`CBI`] elements is the [`FW_CONFIG`] field. This config is used at run time to select different hardware options or behaviours, and is defined generally on a board by board basis. -The `FW_CONFIG` block is limited to 32 bits. The 32 bits are divided into individual + +The [`FW_CONFIG`] block is limited to 32 bits. The 32 bits are divided into individual fields of varying sizes. Each field has defined values that may be set to control the behaviour according to the definition for that board. @@ -30,19 +23,17 @@ Device tree is used to define and specify the field sizes and values. ## Devicetree Nodes -The `FW_CONFIG` device tree nodes are defined via the -[cros-ec-cbi-fw-config](../zephyr/dts/bindings/cbi/cros-ec-cbi-fw-config.yaml) -and -[cros-ec-cbi-fw-config-value](../zephyr/dts/bindings/cbi/cros-ec-cbi-fw-config-value.yaml) +The [`FW_CONFIG`] device tree nodes are defined via the [`cros-ec-cbi-fw-config`] and +[`cros-ec-cbi-fw-config-value`] YAML bindings. -The `cros-ec-cbi-fw-config` bindings define the name, starting bit and size of each field. -The `cros-ec-cbi-fw-config-value` bindings allow names/values to be defined for each +The [`cros-ec-cbi-fw-config`] bindings define the name, starting bit and size of each field. +The [`cros-ec-cbi-fw-config-value`] bindings allow names/values to be defined for each value that may be stored in the field. One of the values may be designated as the default, which is used if -the CBI data cannot be accessed. +the [`CBI`] data cannot be accessed. -Spare CBI FW_CONFIG fields are always initialised as zeros, so that +Spare [`CBI`] [`FW_CONFIG`] fields are always initialised as zeros, so that future fields will have a guaranteed value, so typically a zero value is used as a default, indicating the default field. @@ -81,12 +72,12 @@ puff-fw-config { The device tree will generate a series of enum values and field names that can used -to read the values (via the CBI driver). +to read the values (via the [`CBI`] driver). ## Board Specific Code -To access the generated enums and names, the CBI driver -should be used to access the CBI API to retrieve selected fields, +To access the generated enums and names, the [`CBI`] driver +should be used to access the [`CBI`] API to retrieve selected fields, and then the defined enums used e.g: ``` @@ -94,21 +85,18 @@ and then the defined enums used e.g: int get_power_watts() { - int ret; - uint32_t val; - - if (dev == null) - return -1; - - ret = cros_cbi_get_fw_config(FW_BJ_POWER, &val); - if (ret < 0) - return -1; - - if (val == BJ_POWER_P65) - return 65; - if (val == BJ_POWER_P90) - return 90; - return -1; + int ret; + uint32_t val; + + ret = cros_cbi_get_fw_config(FW_BJ_POWER, &val); + if (ret < 0) + return -1; + + if (val == BJ_POWER_P65) + return 65; + if (val == BJ_POWER_P90) + return 90; + return -1; } ``` @@ -118,4 +106,12 @@ No threads used in this feature. ## Testing and Debugging -There are unit tests. +The [`ectool cbi`] command can be used to read and set the [`FW_CONFIG`]. + + +[`CBI`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md +[`CBI Configuration`]: ./zephyr_cbi.md +[`cros-ec-cbi-fw-config`]: ../../zephyr/dts/bindings/cbi/cros-ec-cbi-fw-config.yaml +[`cros-ec-cbi-fw-config-value`]: ../../zephyr/dts/bindings/cbi/cros-ec-cbi-fw-config-value.yaml +[`ectool cbi`]: ./zephyr_cbi.md#testing-and-debugging +[`FW_CONFIG`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/firmware_config.md diff --git a/docs/zephyr/zephyr_new_board_checklist.md b/docs/zephyr/zephyr_new_board_checklist.md index e3bb065279..f83aa3a188 100644 --- a/docs/zephyr/zephyr_new_board_checklist.md +++ b/docs/zephyr/zephyr_new_board_checklist.md @@ -59,8 +59,7 @@ EC Feature | Ne [Configure I2C Buses](./zephyr_i2c.md) | yes [Configure GPIO](./zephyr_gpio.md) | yes [Configure Batteries](./zephyr_battery.md) | no -[Configure CrOS Board Information (CBI) (TODO)](./zephyr_template.md) | no -[Configure CrOS CBI FW CONFIG](./zephyr_fw_config.md) | no +[Configure CrOS Board Information (CBI)](./zephyr_cbi.md) | no [Configure Keyboard (TODO)](./zephyr_template.md) | no [Configure LEDs (TODO)](./zephyr_template.md) | no [Configure Motion Sensors](./zephyr_motionsense.md) | no diff --git a/docs/zephyr/zephyr_ssfc.md b/docs/zephyr/zephyr_ssfc.md new file mode 100644 index 0000000000..d40fdbc9c4 --- /dev/null +++ b/docs/zephyr/zephyr_ssfc.md @@ -0,0 +1,104 @@ +# Zephyr CBI SSFC Configuration and Use. + +[TOC] + +## Overview + +Zephyr [`SSFC`] [`CBI Configuration`] + +## Kconfig Options + +The CrOS Board Information [`CBI`] feature is enabled with the +CONFIG_PLATFORM_EC_CBI_EEPROM Kconfig, as defined in the [`CBI Configuration`]. + +One of the [`CBI`] elements is the Second Source Factory Cache [`SSFC`] field. +This config is used at run time to select different hardware options or behaviours, and +is defined generally on a board by board basis. The [`SSFC`] describes later decisions +for a board to indicate alternate second sourced hardware stuffing +which can be used by the EC to know which drivers to load. + +The [`SSFC`] block is limited to 32 bits. The 32 bits are divided into individual +fields of varying sizes. Each field has defined values that may be set to control +the behaviour according to the definition for that board. + +Device tree is used to define and specify the field sizes and values. + +## Devicetree Nodes + +The [`SSFC`] device tree nodes are defined via the [`named-cbi-ssfc`] and +[`named-cbi-ssfc-value`] YAML bindings. + +The [`named-cbi-ssfc`] bindings define the name and size of each field. +The [`named-cbi-ssfc-value`] bindings allow names/values to be defined for each +value that may be stored in the field. +One of the values may be designated as the default, which is used if +the [`CBI`] data cannot be accessed. + +Spare [`CBI`] [`SSFC`] fields are always initialised as zeros, so that +future fields will have a guaranteed value, so typically a zero +value is used as a default, indicating the default field. + +An example definition is: +``` +cbi-ssfc { + compatible = "named-cbi-ssfc"; + base_sensor { + enum-name = "BASE_SENSOR"; + size = <3>; + base_sensor_0: bmi160 { + compatible = "named-cbi-ssfc-value"; + status = "okay"; + value = <1>; + }; + }; + lid_sensor { + enum-name = "LID_SENSOR"; + size = <3>; + lid_sensor_0: bma255 { + compatible = "named-cbi-ssfc-value"; + status = "okay"; + value = <1>; + }; + }; + lightbar { + enum-name = "LIGHTBAR"; + size = <2>; + lightbar_0: 10_led { + compatible = "named-cbi-ssfc-value"; + status = "okay"; + value = <1>; + }; + }; +}; +``` + +## Board Specific Code + +To access the presence of an [`SSFC`] component, the [`CBI`] driver +should be used to access the [`CBI`] API to check for an [`SSFC`] match e.g: + +``` +#include "cros_cbi.h" + + bool is_base_sensor_bmi160(void) + { + return cros_cbi_ssfc_check_match( + CBI_SSFC_VALUE_ID(DT_NODELABEL(base_sensor_0))); + } +``` + +## Threads + +No threads used in this feature. + +## Testing and Debugging + +The [`ectool cbi`] command can be used to read and set the [`SSFC`]. + + +[`CBI`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md +[`CBI Configuration`]: ./zephyr_cbi.md +[`ectool cbi`]: ./zephyr_cbi.md#testing-and-debugging +[`named-cbi-ssfc`]: ../../zephyr/dts/bindings/cbi/named-cbi-fw-config.yaml +[`named-cbi-ssfc-value`]: ../../zephyr/dts/bindings/cbi/named-cbi-fw-config-value.yaml +[`SSFC`]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/firmware_config.md diff --git a/zephyr/Kconfig b/zephyr/Kconfig index 755f58200a..c25dd99942 100644 --- a/zephyr/Kconfig +++ b/zephyr/Kconfig @@ -39,6 +39,7 @@ rsource "Kconfig.ap_power" rsource "Kconfig.battery" rsource "Kconfig.charger" rsource "Kconfig.board_version" +rsource "Kconfig.cbi" rsource "Kconfig.console" rsource "Kconfig.console_cmd_mem" rsource "Kconfig.debug_assert" @@ -161,54 +162,6 @@ config PLATFORM_EC_BRINGUP - And more! You can search the codebase for CONFIG_BRINGUP to see all of the features this flag will toggle. -config PLATFORM_EC_BYPASS_CBI_EEPROM_WP_CHECK - bool "Bypass CBI EEPROM Write Protect" - help - Bypass the CBI EEPROM write protect checks. This should ONLY be - defined during bringup, and should never be defined on a shipping or - release platform. - - When defined, ectool can be used to reprogram all CBI fields, - regardless of the state of the hardware write protect. - -config PLATFORM_EC_EEPROM_CBI_WP - bool "EC can independently set the CBI EEPROM WP signal" - help - Define this if the EC can independently set the CBI EEPROM WP - signal. The accompanying hardware must ensure that the CBI WP gets - latched and is only reset when EC_RST_ODL is asserted. - select PLATFORM_EC_BYPASS_CBI_EEPROM_WP_CHECK - -choice PLATFORM_EC_CBI_STORAGE_TYPE - prompt "Select CBI storage Type" - optional - help - CBI is a means for accessing board information, typically set - during the factory process. This allows selection of the physical - storage of CBI source. - - See here for detailed information on CBI: - - https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md - -config PLATFORM_EC_CBI_EEPROM - bool "CBI EEPROM support" - depends on PLATFORM_EC_I2C - help - Enables Chromium OS Board Info (CBI) from EEPROM. - - One must specify both I2C_PORT_EEPROM and I2C_ADDR_EEPROM_FLAGS to the - CBI EEPROM's i2c port and 7-bit i2c address. - -config PLATFORM_EC_CBI_GPIO - bool "CBI GPIO support" - help - Enables Chromium OS Board Info (CBI) from strapping pins. EC reads - the BOARD ID and SKU ID from GPIOs and then substantiate in-memory - CBI for AP to query. - -endchoice - config PLATFORM_EC_CHIPSET_RESET_HOOK bool "Provide a hook for when the AP resets" default y diff --git a/zephyr/Kconfig.cbi b/zephyr/Kconfig.cbi new file mode 100644 index 0000000000..7236916938 --- /dev/null +++ b/zephyr/Kconfig.cbi @@ -0,0 +1,51 @@ +# Copyright 2022 The Chromium OS Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that can be +# found in the LICENSE file. + +config PLATFORM_EC_BYPASS_CBI_EEPROM_WP_CHECK + bool "Bypass CBI EEPROM Write Protect" + help + Bypass the CBI EEPROM write protect checks. This should ONLY be + defined during bringup, and should never be defined on a shipping or + release platform. + + When defined, ectool can be used to reprogram all CBI fields, + regardless of the state of the hardware write protect. + +config PLATFORM_EC_EEPROM_CBI_WP + bool "EC can independently set the CBI EEPROM WP signal" + help + Define this if the EC can independently set the CBI EEPROM WP + signal. The accompanying hardware must ensure that the CBI WP gets + latched and is only reset when EC_RST_ODL is asserted. + select PLATFORM_EC_BYPASS_CBI_EEPROM_WP_CHECK + +choice PLATFORM_EC_CBI_STORAGE_TYPE + prompt "Select CBI storage Type" + optional + help + CBI is a means for accessing board information, typically set + during the factory process. This allows selection of the physical + storage of CBI source. + + See here for detailed information on CBI: + + https://chromium.googlesource.com/chromiumos/docs/+/HEAD/design_docs/cros_board_info.md + +config PLATFORM_EC_CBI_EEPROM + bool "CBI EEPROM support" + depends on PLATFORM_EC_I2C + help + Enables Chromium OS Board Info (CBI) from EEPROM. + + One must specify both I2C_PORT_EEPROM and I2C_ADDR_EEPROM_FLAGS to the + CBI EEPROM's i2c port and 7-bit i2c address. + +config PLATFORM_EC_CBI_GPIO + bool "CBI GPIO support" + help + Enables Chromium OS Board Info (CBI) from strapping pins. EC reads + the BOARD ID and SKU ID from GPIOs and then substantiate in-memory + CBI for AP to query. + +endchoice |