|
| 1 | +.. _porting_ecfw_custom_hw: |
| 2 | + |
| 3 | +Port Basic EC FW to custom HW design |
| 4 | +#################################### |
| 5 | + |
| 6 | +.. contents:: |
| 7 | + :local: |
| 8 | + :depth: 3 |
| 9 | + |
| 10 | +Overview |
| 11 | +******** |
| 12 | +This application note contains generic guidelines to adapt basic EC open source |
| 13 | +to a custom HW design. |
| 14 | + |
| 15 | +Basic Open EC FW is designed as an application that runs on Zephyr RTOS, this project links to Zephyr and other dependencies. |
| 16 | +As such this repo contains only application-specific files, most of EC SoC HW support is contained under Zephyr project. |
| 17 | + |
| 18 | + .. image:: ../ecfw_zephyr_repos.png |
| 19 | + :align: center |
| 20 | + |
| 21 | + |
| 22 | +EC SoC and architecture |
| 23 | +======================= |
| 24 | +When porting the application to custom hardware, we must ensure the desired EC SoC and architecture are already supported by Zephyr RTOS. |
| 25 | +Zephyr project is not limited to embedded controllers, but it supports major EC vendors: Microchip, ITE, Nuvoton, Realtek. |
| 26 | +However, even if an EC vendor is supported not all their EC chips have Zephyr support. |
| 27 | +Refer to `Zephyr's board support`_ |
| 28 | + |
| 29 | +Note that EC SoC support in Zephyr RTOS project needs to included all drivers required by |
| 30 | +Basic Open EC FW are available. The list below presents the minimum drivers required by the EC application to |
| 31 | +boot in an eSPI-based Intel platform. |
| 32 | + |
| 33 | +* UART |
| 34 | +* GPIO |
| 35 | +* RTOS timer |
| 36 | +* I2C - Port 80 visualization if board supports it. |
| 37 | +* eSPI - Required by power sequencing module |
| 38 | +* ACPI - Required by SMC host module (EC - BIOS interactions). |
| 39 | +* eSPI TAF - Required for EC flash sharing boot and boot configuration for EC as root of trust. |
| 40 | + |
| 41 | +The following drivers are needed to exercise other non-boot critical features: |
| 42 | + |
| 43 | +* PS/2 - for PS/2 devices management |
| 44 | +* Keyscan - for keyboard matrix |
| 45 | + |
| 46 | +These drivers are required to enable advanced features such as thermal and fan |
| 47 | +control. |
| 48 | + |
| 49 | +* PECI - for thermal module |
| 50 | +* TACH - for thermal module |
| 51 | +* ADC - for thermal module |
| 52 | +* PWM - for fan control |
| 53 | + |
| 54 | +Board support |
| 55 | +============= |
| 56 | + |
| 57 | +`Zephyr's RTOS HW model`_ is defined in device tree files, where a board describes at least one SoC and all its features. |
| 58 | +Zephyr RTOS project repository supports many of EC vendors' evaluation boards which can be used in standalone mode. |
| 59 | +The board files enumerate all EC HW features enabled for a HW design and their settings e.g. EC CPU frequency, which pins are used as I2C, UART, if eSPI enabled or not, etc. |
| 60 | + |
| 61 | + .. image:: https://docs.zephyrproject.org/3.4.0/_images/hierarchy.png |
| 62 | + :align: center |
| 63 | + |
| 64 | +On the other hand, in addition to EC FW application modules, this project provides additional out-of-tree boards for Intel Reference Platforms using an Embedded controller. |
| 65 | +These are based on EC SoC vendor reference evaluation board and modified using Zephyr board porting guide. |
| 66 | +Note the provided board device tree files are the same in all Intel RVP designs using same EC chip. |
| 67 | +This folder also contains the default KConfig for a board, this will list all Zephyr drivers to be enabled for a particular board. |
| 68 | + |
| 69 | +Within the EC FW folders, the other relevant set of files are the ones that indicate which pins that are in GPIO mode and under direct control of EC FW. |
| 70 | +These files contain the EC GPIO mapping for a particular RVP design and their I/O configuration. |
| 71 | +Note that even among designs using same EC chip, the EC GPIOS could be mapped differently in each RVP family. |
| 72 | + |
| 73 | + .. image:: oot_boards_vs_boards.png |
| 74 | + :align: center |
| 75 | + |
| 76 | + |
| 77 | +Since the MECC cards are usually supported as part of Zephyr RTOS project, they are not part of out-of-tree folder. |
| 78 | +Override for customization in such cases is done via both device tree overlay files. |
| 79 | + |
| 80 | + .. image:: mecc_cards_overlay.png |
| 81 | + :align: center |
| 82 | + |
| 83 | + |
| 84 | +EC porting guidelines |
| 85 | +********************* |
| 86 | + |
| 87 | +1. Create device tree board folder |
| 88 | +================================== |
| 89 | + |
| 90 | +1.1. Locate the closest reference design which defines the desired features under out-of-tree boards and gpio-mapping folders, e.g. if the design is based on Meteor lake and is intended |
| 91 | +for a mobile design take Meteor lake P as reference. To see all reference designs files use the following command: |
| 92 | + |
| 93 | +.. code-block:: c |
| 94 | +
|
| 95 | + tree out_of_tree_boards/ -P *.dts -I support |
| 96 | +
|
| 97 | +Above command will list all reference out-of-tree boards |
| 98 | + |
| 99 | + .. image:: oot_boards.png |
| 100 | + :align: center |
| 101 | + |
| 102 | +1.2. Copy the folder or modify the board as needed, e.g. MTL-S LJ is an example of customization that refers to MTL-S but using different packaging. |
| 103 | + |
| 104 | +MECC cards |
| 105 | +---------- |
| 106 | +To use a different MECC card with a different EC SoC vendor, the vendor should add its Hardware Abstraction Layer (HAL) and board support package (BSP) |
| 107 | +to Zephyr RTOS. See `Zephyr's porting guide`_ |
| 108 | + |
| 109 | +Custom HW |
| 110 | +--------- |
| 111 | +If the custom HW does not follow any of Intel RVP EC GPIO mapping, we need to create the board files using Zephyr generic guidelinesprovided by Zephyr |
| 112 | +https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#create-your-board-directory |
| 113 | + |
| 114 | + |
| 115 | +2. Customize EC FW for a board |
| 116 | +============================== |
| 117 | + |
| 118 | + |
| 119 | +2.1 Map EC SoC drivers to application features |
| 120 | +---------------------------------------------- |
| 121 | +Zephyr uses device tree to describe hardware both EC SoC and board's peripherals. |
| 122 | +Currently, the EC FW abstracts the device tree using friendly macros which can be customized when |
| 123 | +using different EC SoC and/or different board. See boards/<vendor> for more details. |
| 124 | + |
| 125 | +.. code-block:: c |
| 126 | +
|
| 127 | + #define I2C_BUS_0 DT_NODELABEL(i2c_smb_0) |
| 128 | +
|
| 129 | +For more details, see `Zephyr's device tree guide`_. |
| 130 | + |
| 131 | + |
| 132 | +2.2 Create EC GPIO mapping |
| 133 | +-------------------------- |
| 134 | + |
| 135 | +As indicated before, EC FW app does not control/configure all GPIOs in the chip but only the ones used |
| 136 | +by the app as GPIOs. When a pin is intended to be controlled by the EC FW framework it should be |
| 137 | +mapped under boardname_chipversion.h to corresponding Zephyr GPIO port and pin. |
| 138 | + |
| 139 | +.. code-block:: c |
| 140 | +
|
| 141 | + #define PCH_PWROK EC_GPIO_106 /* Board #1 Port A, Pin B */ |
| 142 | + #define PCH_PWROK EC_GPIO_036 /* Board #2 Port B, Pin C */ |
| 143 | +
|
| 144 | +.. note:: EC_GPIO_XXX is a SoC specific macro, which abstracts GPIO port and |
| 145 | + GPIO pin number since Zephyr supports logical GPIO ports and |
| 146 | + EC FW requires the flexibility to map same signal to different port/pins. |
| 147 | + |
| 148 | +Similarly, boardname_chipversion.c should contain the actual pin configuration |
| 149 | +required by the application input/output, open drain and so on. |
| 150 | +See `Zephyr's GPIO reference`_ for Zephyr GPIO flags. |
| 151 | + |
| 152 | + .. code-block:: c |
| 153 | +
|
| 154 | + tree -L 2 boards/ -P *.c |
| 155 | +
|
| 156 | +
|
| 157 | + .. image:: board_ec_mapping.png |
| 158 | + :align: center |
| 159 | + |
| 160 | + |
| 161 | +2.3 Create EC board configuration override |
| 162 | +------------------------------------------ |
| 163 | + |
| 164 | +To customize EC FW features per board, use a project file configuration overlay. |
| 165 | + |
| 166 | + .. image:: mtl_p_board_specific_files.png |
| 167 | + :align: center |
| 168 | + |
| 169 | +During compilation time, the board-specific settings will be applied after the overall EC FW default project settings and |
| 170 | +default board KConfig settings. |
| 171 | +This method allows to disabled features either unwanted or not yet ready to be evaluated. |
| 172 | + |
| 173 | +.. code-block:: text |
| 174 | +
|
| 175 | + Parsing ~/ecfw-zephyr/Kconfig |
| 176 | + Loaded configuration '~/ecfw-zephyr/out_of_tree_boards/boards/arm/mec1501_mtl_p/mec1501_mtl_p_defconfig' |
| 177 | + Merged configuration '~/ecfw-zephyr/prj.conf' |
| 178 | + Merged configuration '~.ecfw-zephyr/boards/mec1501_mtl_p.conf' |
| 179 | +
|
| 180 | +
|
| 181 | +
|
| 182 | +
|
| 183 | +3. Verify EC FW build for new board |
| 184 | +=================================== |
| 185 | +Once aforementioned files are added, the EC firmware can be built using the configuration as any other Zephyr application. |
| 186 | + |
| 187 | +https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#build-test-and-fix |
| 188 | + |
| 189 | + |
| 190 | + |
| 191 | +.. _Zephyr's board support: |
| 192 | + https://docs.zephyrproject.org/3.4.0/boards/index.html# |
| 193 | + |
| 194 | +.. _Zephyr's RTOS HW model: |
| 195 | + https://docs.zephyrproject.org/3.4.0/hardware/porting/board_porting.html#hardware-support-hierarchy |
| 196 | + |
| 197 | +.. _Zephyr's porting guide: |
| 198 | + https://docs.zephyrproject.org/3.4.0/hardware/porting/board_porting.html#board-porting-guide |
| 199 | + |
| 200 | +.. _Zephyr's device tree guide: |
| 201 | + https://docs.zephyrproject.org/3.4.0/guides/dts/index.html |
| 202 | + |
| 203 | +.. _Zephyr's GPIO reference: |
| 204 | + https://docs.zephyrproject.org/3.4.0/reference/peripherals/gpio.html |
0 commit comments