Skip to content

Commit f0347e8

Browse files
committed
doc: Add EC porting guidelines
Add application note about EC porting to custom HW Signed-off-by: Jose Alberto Meza <[email protected]>
1 parent f410336 commit f0347e8

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+1146
-882
lines changed

doc/reference/application_notes.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ main flows, implementation details and configuration options supported.
1414

1515
soc_debug_awareness/index.rst
1616
custom_kscan/index.rst
17+
porting_ecfw_custom_hw/index.rst
Loading
Loading
Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
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
Loading
Loading
Loading
Loading

doc/reference/supported_hw.rst

Lines changed: 12 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -48,75 +48,18 @@ EC vendors in an Intel RVP.
4848
| | RVP + ITE8002 card | |
4949
+--------------------+--------------------------+-------------------------+
5050

51-
Other EC SoC
52-
============
53-
In order to use a different MECC card with a different EC SoC vendor, the vendor
54-
should add its Hardware Abstraction Layer (HAL) and board support package (BSP)
55-
to Zephyr RTOS. See `Zephyr's porting guide`_
51+
Custom HW
52+
=========
53+
For generic guidelines to adapt basic EC open source to custom HW design.
5654

57-
The list below presents the minimum drivers required by the EC application to
58-
boot an eSPI-based Intel platform.
55+
.. toctree::
56+
:maxdepth: 1
5957

60-
* UART
61-
* GPIO
62-
* RTOS timer
63-
* I2C - Port 80 visualization if board supports it.
64-
* eSPI - Required by power sequencing module
65-
* ACPI - Required by SMC host module (EC - BIOS interactions).
58+
porting_ecfw_custom_hw/index.rst
6659

67-
The following drivers are needed to exercise other non-boot critical features:
6860

69-
* PS/2 - for PS/2 devices management
70-
* Keyscan - for keyboard matrix
71-
72-
These drivers are required to enable advanced features such as thermal and fan
73-
control.
74-
75-
* PECI - for thermal module
76-
* TACH - for thermal module
77-
* ADC - for thermal module
78-
* PWM - for fan control
79-
80-
Customize EC FW framework for other EC SoC
81-
==========================================
82-
83-
Zephyr uses device tree to describe hardware both EC SoC and board's peripherals.
84-
The EC FW abstracts the device tree using friendly macros which can be customized when
85-
using different EC SoC and/or different board. See boards/<vendor> for more details
86-
87-
.. code-block:: c
88-
89-
#define I2C_BUS_0 DT_NODELABEL(i2c_smb_0)
90-
91-
For more details, see `Zephyr's device tree guide`_.
92-
93-
GPIO initialization
94-
===================
95-
EC FW app doesn't control/configure all GPIOs on the chip but only the ones used
96-
by the app. This is an important delegation to BSP's where generic app pins
97-
are not configured.
98-
99-
.. note:: For current supported HW via MECC card, see boards folder.
100-
101-
When a pin is intended to be controlled by the EC FW framework it should be
102-
mapped under boardname_chipversion.h to corresponding Zephyr GPIO port and pin.
103-
104-
.. code-block:: c
105-
106-
#define PCH_PWROK EC_GPIO_106 /* Board #1 Port A, Pin B */
107-
#define PCH_PWROK EC_GPIO_036 /* Board #2 Port B, Pin C */
108-
109-
.. note:: EC_GPIO_XXX is a SoC specific macro, which abstracts GPIO port and
110-
GPIO pin number since Zephyr supports logical GPIO ports and
111-
EC FW requires the flexibility to map a signal to different pins.
112-
113-
Similarly, boardname_chipversion.c should contain the actual pin configuration
114-
required by the application input/output, open drain and so on.
115-
See `Zephyr's GPIO reference`_ for Zephyr GPIO flags.
116-
117-
118-
HW limitations
119-
==============
61+
MECC card HW limitations
62+
========================
12063

12164
Most of the signals used by onboard EC are routed to MECC connector, however
12265
some signals may be missing on MECC compared to onboard EC.
@@ -134,6 +77,8 @@ card. Refer to table below for guidance about what can be verified end-to-end.
13477
| Area | Feature | MTL-P + | MTL-S | MTL-P |
13578
| | | MEC172x | onboard | onboard |
13679
+==================+==========================+=========+=========+=========+
80+
| | MECC spec | 1.0 | 1.0 | 1.0 |
81+
+------------------+--------------------------+---------+---------+---------+
13782
| Power sequencing | ACPI power (Sx) | Yes | Yes | Yes |
13883
+------------------+--------------------------+---------+---------+---------+
13984
| | Deep sleep (DSx) | No | Yes | No |
@@ -165,6 +110,8 @@ card. Refer to table below for guidance about what can be verified end-to-end.
165110
| | Serial port (UART) | Yes(4) | Yes | Yes |
166111
+------------------+--------------------------+---------+---------+---------+
167112

113+
114+
168115
.. note:: (1) MEC172x HW revision 2 supports PS2 Keyboard on PortA and PS2 Mouse
169116
on PortB. Mouse has not been verified though.
170117

@@ -180,12 +127,3 @@ card. Refer to table below for guidance about what can be verified end-to-end.
180127

181128
.. _Platform design guide:
182129
https://www.intel.com/content/www/us/en/programmable/documentation/lit-index.html
183-
184-
.. _Zephyr's porting guide:
185-
https://docs.zephyrproject.org/latest/guides/porting/board_porting.html
186-
187-
.. _Zephyr's device tree guide:
188-
https://docs.zephyrproject.org/latest/guides/dts/index.html
189-
190-
.. _Zephyr's GPIO reference:
191-
https://docs.zephyrproject.org/latest/reference/peripherals/gpio.html

docs/_images/board_ec_mapping.png

4.65 KB
Loading

docs/_images/mecc_cards_overlay.png

3.62 KB
Loading
7.81 KB
Loading

docs/_images/oot_boards.png

7.05 KB
Loading

docs/_images/oot_boards_vs_boards.png

67.9 KB
Loading

0 commit comments

Comments
 (0)