Skip to content

Commit 3df5302

Browse files
barnas-michalChromeos LUCI
barnas-michal
authored and
Chromeos LUCI
committed
zephyr: extract information about MKBP from hostcmd doc
This commit extracts the information about MKBP protocol and its configuration from AP/EC communication documentation to separate file. BRANCH=main BUG=b:208438167 TEST=generate preview Change-Id: I2c579472170de73b944183793b324ee72f0631d8 Signed-off-by: Michał Barnaś <[email protected]> Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3500405 Reviewed-by: Keith Short <[email protected]>
1 parent 53a2adf commit 3df5302

File tree

2 files changed

+111
-83
lines changed

2 files changed

+111
-83
lines changed

‎docs/zephyr/zephyr_ap_ec_comm.md‎

Lines changed: 3 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -64,32 +64,8 @@ Kconfig sub-options | Default | Documentation
6464

6565
### MKBP - Matrix Keyboard Protocol
6666

67-
MKBP was originally used to send keyboard events to AP OS.
68-
Later, more functionalities were added and more types of events can be sent
69-
using this protocol. It can transfer information about keystrokes, sensors,
70-
switches, fingerprints and more.
71-
72-
Kconfig sub-options | Default | Documentation
73-
:------------------------------------------- | :---------: | :------------
74-
`CONFIG_PLATFORM_EC_MKBP_INPUT_DEVICES` | n | [MKBP input devices]
75-
`CONFIG_PLATFORM_EC_MKBP_EVENT` | n | [MKBP event]
76-
77-
The following options must be enabled to use respective masks specified in
78-
device tree. See [Device Tree nodes](#device-tree-nodes) paragraph for details.
79-
80-
Kconfig sub-options | Default | Documentation
81-
:---------------------------------------------- | :---------: | :------------
82-
`CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK` | n | [MKBP event wake-up mask]
83-
`CONFIG_PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK`| n | [MKBP host event wake-up mask]
84-
85-
The following options select the delivery method of MKBP messages.
86-
87-
Kconfig sub-options | Default | Documentation
88-
:----------------------------------------------- | :---------: | :------------
89-
`CONFIG_PLATFORM_EC_MKBP_USE_GPIO` | y | [MKBP gpio]
90-
`CONFIG_PLATFORM_EC_MKBP_USE_HOST_EVENT` | n | [MKBP host event]
91-
`CONFIG_PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT`| n | [MKBP gpio and host event]
92-
`CONFIG_PLATFORM_EC_MKBP_USE_CUSTOM` | n | [MKBP custom]
67+
See the [MKBP documentation] for information about configuration of MKBP
68+
protocol.
9369

9470
### Debug
9571

@@ -152,47 +128,6 @@ The node's required properties are defined in yaml files: [SHI bindings]
152128
}
153129
```
154130

155-
### MKBP Wake-up Masks
156-
157-
The EC can wake up the AP from sleep modes based on multiple event types.
158-
A wake-up mask specifies which specific event types are able to wake the AP.
159-
160-
For x86 based Chromebooks, the wake-up mask is controlled by the AP firmware
161-
directly using host commands `EC_CMD_HOST_EVENT_SET_SMI_MASK`,
162-
`EC_CMD_HOST_EVENT_SET_SCI_MASK` and `EC_CMD_HOST_EVENT_SET_WAKE_MASK`.
163-
164-
For ARM based Chromebooks, the wake-up mask is defined as device tree nodes,
165-
one for MKBP events and one for generic host events.
166-
They have respective Kconfig options, which must be enabled to take the masks
167-
into account.
168-
169-
Both masks have to be compatible with binding file: [MKBP event mask yaml]
170-
171-
Possible enums to use in these nodes are specified in file: [MKBP event mask enums]
172-
173-
```
174-
/ {
175-
ec-mkbp-host-event-wakeup-mask {
176-
compatible = "ec-wake-mask-event";
177-
wakeup-mask = <(HOST_EVENT_LID_OPEN |
178-
HOST_EVENT_POWER_BUTTON |
179-
HOST_EVENT_AC_CONNECTED |
180-
HOST_EVENT_AC_DISCONNECTED |
181-
HOST_EVENT_HANG_DETECT |
182-
HOST_EVENT_RTC |
183-
HOST_EVENT_MODE_CHANGE |
184-
HOST_EVENT_DEVICE)>;
185-
};
186-
187-
ec-mkbp-event-wakeup-mask {
188-
compatible = "ec-wake-mask-event";
189-
wakeup-mask = <(MKBP_EVENT_KEY_MATRIX |
190-
MKBP_EVENT_HOST_EVENT |
191-
MKBP_EVENT_SENSOR_FIFO)>;
192-
};
193-
}
194-
```
195-
196131
## Board Specific Code
197132

198133
No board specific code is required.
@@ -246,10 +181,6 @@ messages visible on EC console since boot-up.
246181

247182
## Examples
248183

249-
[Lazor MKBP wake-up](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/gpio.dts?q=ec-mkbp-host-event-wakeup-mask)
250-
251-
[Lazor MKBP Kconfig](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/prj.conf?q=CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK)
252-
253184
[NPCX eSPI selection](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/cros/nuvoton/npcx.dtsi?q=cros-ec,espi)
254185

255186
[NPCX SHI definition](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/cros/nuvoton/npcx.dtsi?q=shi)
@@ -272,25 +203,14 @@ Links to the documentation
272203
[Host command console buffer size]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.console?q=%22config%20PLATFORM_EC_HOSTCMD_CONSOLE_BUF_SIZE%22
273204
[Host command - status]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_HOST_COMMAND_STATUS%22
274205

275-
[MKBP input devices]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_INPUT_DEVICES%22
276-
[MKBP event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT%22
277-
278-
[MKBP event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK%22
279-
[MKBP host event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK%22
280-
281-
[MKBP gpio]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO%22
282-
[MKBP host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_HOST_EVENT%22
283-
[MKBP gpio and host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT%22
284-
[MKBP custom]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_CUSTOM%22
206+
[MKBP documentation]:zephyr_mkbp.md
285207

286208
[Debug off]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_OFF%22
287209
[Debug normal]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_NORMAL%22
288210
[Debug every]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_EVERY%22
289211
[Debug params]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20HCDEBUG_PARAMS%22
290212

291213
[SHI bindings]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/cros_shi/
292-
[MKBP event mask yaml]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/cros_mkbp_event/ec-mkbp-event.yaml
293-
[MKBP event mask enums]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/dt-bindings/wake_mask_event_defines.h
294214

295215
[CrOS EC documentation]:../ap-ec-comm.md#ectool
296216
[stress test]:../ap-ec-comm.md#stress-test

‎docs/zephyr/zephyr_mkbp.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# MKBP - Matrix Keyboard Protocol
2+
3+
[TOC]
4+
5+
## Overview
6+
7+
[MKBP] was originally used to send keyboard events to AP OS.
8+
Later, more functionalities were added and more types of events can be sent
9+
using this protocol. It can transfer information about keystrokes, sensors,
10+
switches, fingerprints and more.
11+
12+
Kconfig sub-options | Default | Documentation
13+
:------------------------------------------- | :---------: | :------------
14+
`CONFIG_PLATFORM_EC_MKBP_INPUT_DEVICES` | n | [MKBP input devices]
15+
`CONFIG_PLATFORM_EC_MKBP_EVENT` | n | [MKBP event]
16+
17+
## Delivery method
18+
19+
The following options select the delivery method of MKBP messages.
20+
21+
Kconfig sub-options | Default | Documentation
22+
:----------------------------------------------- | :---------: | :------------
23+
`CONFIG_PLATFORM_EC_MKBP_USE_GPIO` | y | [MKBP gpio]
24+
`CONFIG_PLATFORM_EC_MKBP_USE_HOST_EVENT` | n | [MKBP host event]
25+
`CONFIG_PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT`| n | [MKBP gpio and host event]
26+
`CONFIG_PLATFORM_EC_MKBP_USE_CUSTOM` | n | [MKBP custom]
27+
28+
## Wake-up masks
29+
30+
The EC can wake up the AP from sleep modes based on multiple event types.
31+
A wake-up mask specifies which specific event types are able to wake the AP.
32+
33+
For x86 based Chromebooks, the wake-up mask is controlled by the AP firmware
34+
directly using host commands `EC_CMD_HOST_EVENT_SET_SMI_MASK`,
35+
`EC_CMD_HOST_EVENT_SET_SCI_MASK` and `EC_CMD_HOST_EVENT_SET_WAKE_MASK`.
36+
37+
For ARM based Chromebooks, the wake-up mask is defined as device tree nodes,
38+
one for MKBP events and one for generic host events.
39+
They have respective Kconfig options, which must be enabled to take the masks
40+
into account.
41+
42+
### Kconfigs
43+
44+
The following options must be enabled to use respective masks specified in
45+
device tree. See [Device Tree nodes](#device-tree-nodes) paragraph for details.
46+
47+
Kconfig sub-options | Default | Documentation
48+
:---------------------------------------------- | :---------: | :------------
49+
`CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK` | n | [MKBP event wake-up mask]
50+
`CONFIG_PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK`| n | [MKBP host event wake-up mask]
51+
52+
### Device Tree nodes
53+
54+
Both masks have to be compatible with binding file: [MKBP event mask yaml]
55+
56+
Possible enums to use in these nodes are specified in file: [MKBP event mask enums]
57+
58+
```
59+
/ {
60+
ec-mkbp-host-event-wakeup-mask {
61+
compatible = "ec-wake-mask-event";
62+
wakeup-mask = <(HOST_EVENT_LID_OPEN |
63+
HOST_EVENT_POWER_BUTTON |
64+
HOST_EVENT_AC_CONNECTED |
65+
HOST_EVENT_AC_DISCONNECTED |
66+
HOST_EVENT_HANG_DETECT |
67+
HOST_EVENT_RTC |
68+
HOST_EVENT_MODE_CHANGE |
69+
HOST_EVENT_DEVICE)>;
70+
};
71+
72+
ec-mkbp-event-wakeup-mask {
73+
compatible = "ec-wake-mask-event";
74+
wakeup-mask = <(MKBP_EVENT_KEY_MATRIX |
75+
MKBP_EVENT_HOST_EVENT |
76+
MKBP_EVENT_SENSOR_FIFO)>;
77+
};
78+
}
79+
```
80+
81+
## Examples
82+
83+
[Lazor MKBP Kconfig](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/prj.conf?q=CONFIG_PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK)
84+
85+
[Lazor wake-up masks](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/projects/trogdor/lazor/gpio.dts?q=ec-mkbp-host-event-wakeup-mask)
86+
87+
For detailed descriptions of the MKBP and host event types, please see
88+
[ec_commands.h](/include/ec_commands.h) header file.
89+
90+
<!--
91+
Links to the documentation
92+
-->
93+
94+
[MKBP]:../ec_terms.md#mkbp
95+
96+
[MKBP input devices]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_INPUT_DEVICES%22
97+
[MKBP event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT%22
98+
99+
[MKBP event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_EVENT_WAKEUP_MASK%22
100+
[MKBP host event wake-up mask]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig?q=%22config%20PLATFORM_EC_MKBP_HOST_EVENT_WAKEUP_MASK%22
101+
102+
[MKBP gpio]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO%22
103+
[MKBP host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_HOST_EVENT%22
104+
[MKBP gpio and host event]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_GPIO_AND_HOST_EVENT%22
105+
[MKBP custom]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.mkbp_event?q=%22config%20PLATFORM_EC_MKBP_USE_CUSTOM%22
106+
107+
[MKBP event mask yaml]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/dts/bindings/cros_mkbp_event/ec-mkbp-event.yaml
108+
[MKBP event mask enums]:https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/include/dt-bindings/wake_mask_event_defines.h

0 commit comments

Comments
 (0)