From: Ricardo Neri <ricardo.neri-calderon@linux.intel.com>
To: x86@kernel.org, Krzysztof Kozlowski <krzk+dt@kernel.org>,
Conor Dooley <conor+dt@kernel.org>, Rob Herring <robh@kernel.org>,
"K. Y. Srinivasan" <kys@microsoft.com>,
Haiyang Zhang <haiyangz@microsoft.com>,
Wei Liu <wei.liu@kernel.org>, Dexuan Cui <decui@microsoft.com>,
Michael Kelley <mhklinux@outlook.com>
Cc: devicetree@vger.kernel.org,
Saurabh Sengar <ssengar@linux.microsoft.com>,
Chris Oo <cho@microsoft.com>,
linux-hyperv@vger.kernel.org,
"Kirill A. Shutemov" <kirill.shutemov@linux.intel.com>,
linux-acpi@vger.kernel.org ,
linux-kernel@vger.kernel.org,
"Ravi V. Shankar" <ravi.v.shankar@intel.com>,
Ricardo Neri <ricardo.neri@intel.com>
Subject: [PATCH v3 06/13] dt-bindings: reserved-memory: Wakeup Mailbox for Intel processors
Date: Sat, 3 May 2025 12:15:08 -0700 [thread overview]
Message-ID: <20250503191515.24041-7-ricardo.neri-calderon@linux.intel.com> (raw)
In-Reply-To: <20250503191515.24041-1-ricardo.neri-calderon@linux.intel.com>
Add DeviceTree bindings for the wakeup mailbox used on Intel processors.
x86 platforms commonly boot secondary CPUs using an INIT assert, de-assert
followed by Start-Up IPI messages. The wakeup mailbox can be used when this
mechanism unavailable.
The wakeup mailbox offers more control to the operating system to boot
secondary CPUs than a spin-table. It allows the reuse of same wakeup vector
for all CPUs while maintaining control over which CPUs to boot and when.
While it is possible to achieve the same level of control using a spin-
table, it would require to specify a separate cpu-release-addr for each
secondary CPU.
Originally-by: Yunhong Jiang <yunhong.jiang@linux.intel.com>
Signed-off-by: Ricardo Neri <ricardo.neri-calderon@linux.intel.com>
---
Changes since v2:
- Implemented the mailbox as a reserved-memory node. Add to it a
`compatible` property. (Krzysztof)
- Explained the relationship between the mailbox and the `enable-mehod`
property of the CPU nodes.
- Expanded the documentation of the binding.
Changes since v1:
- Added more details to the description of the binding.
- Added requirement a new requirement for cpu@N nodes to add an
`enable-method`.
---
.../reserved-memory/intel,wakeup-mailbox.yaml | 87 +++++++++++++++++++
1 file changed, 87 insertions(+)
create mode 100644 Documentation/devicetree/bindings/reserved-memory/intel,wakeup-mailbox.yaml
diff --git a/Documentation/devicetree/bindings/reserved-memory/intel,wakeup-mailbox.yaml b/Documentation/devicetree/bindings/reserved-memory/intel,wakeup-mailbox.yaml
new file mode 100644
index 000000000000..d97755b4673d
--- /dev/null
+++ b/Documentation/devicetree/bindings/reserved-memory/intel,wakeup-mailbox.yaml
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/reserved-memory/intel,wakeup-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Wakeup Mailbox for Intel processors
+
+description: |
+ The Wakeup Mailbox provides a mechanism for the operating system to wake up
+ secondary CPUs on Intel processors. It is an alternative to the INIT-!INIT-
+ SIPI sequence used on most x86 systems.
+
+ Firmware must define the enable-method property in the CPU nodes as
+ "intel,wakeup-mailbox" to use the mailbox.
+
+ Firmware implements the wakeup mailbox as a 4KB-aligned memory region of size
+ of 4KB. It is memory that the firmware reserves so that each secondary CPU can
+ have the operating system send a single message to them. The firmware is
+ responsible for putting the secondary CPUs in a state to check the mailbox.
+
+ The structure of the mailbox is as follows:
+
+ Field Byte Byte Description
+ Length Offset
+ ------------------------------------------------------------------------------
+ Command 2 0 Command to wake up the secondary CPU:
+ 0: Noop
+ 1: Wakeup: Jump to the wakeup_vector
+ 2-0xFFFF: Reserved:
+ Reserved 2 2 Must be 0.
+ APIC_ID 4 4 APIC ID of the secondary CPU to wake up.
+ Wakeup_Vector 8 8 The wakeup address for the secondary CPU.
+ ReservedForOs 2032 16 Reserved for OS use.
+ ReservedForFW 2048 2048 Reserved for firmware use.
+ ------------------------------------------------------------------------------
+
+ To wake up a secondary CPU, the operating system 1) prepares the wakeup
+ routine; 2) populates the address of the wakeup routine address into the
+ Wakeup_Vector field; 3) populates the APIC_ID field with the APIC ID of the
+ secondary CPU; 4) writes Wakeup in the Command field. Upon receiving the
+ Wakeup command, the secondary CPU acknowledges the command by writing Noop in
+ the Command field and jumps to the Wakeup_Vector. The operating system can
+ send the next command only after the Command field is changed to Noop.
+
+ The secondary CPU will no longer check the mailbox after waking up. The
+ secondary CPU must ignore the command if its APIC_ID written in the mailbox
+ does not match its own.
+
+ When entering the Wakeup_Vector, interrupts must be disabled and 64-bit
+ addressing mode must be enabled. Paging mode must be enabled. The virtual
+ address of the Wakeup_Vector page must be equal to its physical address.
+ Segment selectors are not used.
+
+maintainers:
+ - Ricardo Neri <ricardo.neri-calderon@linux.intel.com>
+
+allOf:
+ - $ref: reserved-memory.yaml
+
+properties:
+ compatible:
+ const: intel,wakeup-mailbox
+
+ alignment:
+ description: The mailbox must be 4KB-aligned.
+ const: 0x1000
+
+required:
+ - compatible
+ - alignment
+ - reg
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ reserved-memory {
+ #address-cells = <2>;
+ #size-cells = <1>;
+
+ wakeup-mailbox@12340000 {
+ compatible = "intel,wakeup-mailbox";
+ alignment = <0x1000>;
+ reg = <0x0 0x12340000 0x1000>;
+ };
+ };
--
2.43.0
next prev parent reply other threads:[~2025-05-03 19:10 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-05-03 19:15 [PATCH v3 00/13] x86/hyperv/hv_vtl: Use a wakeup mailbox to boot secondary CPUs Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 01/13] x86/acpi: Add a helper function to setup the wakeup mailbox Ricardo Neri
2025-05-05 9:50 ` Rafael J. Wysocki
2025-05-06 5:20 ` Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 02/13] x86/acpi: Add a helper function to get a pointer to " Ricardo Neri
2025-05-05 9:55 ` Rafael J. Wysocki
2025-05-06 5:23 ` Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 03/13] x86/acpi: Move acpi_wakeup_cpu() and helpers to smpboot.c Ricardo Neri
2025-05-05 10:03 ` Rafael J. Wysocki
2025-05-06 5:37 ` Ricardo Neri
2025-05-06 17:26 ` Rafael J. Wysocki
2025-05-07 11:22 ` Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 04/13] dt-bindings: x86: Add CPU bindings for x86 Ricardo Neri
2025-05-03 20:33 ` Rob Herring (Arm)
2025-05-04 16:45 ` Krzysztof Kozlowski
2025-05-06 4:52 ` Ricardo Neri
2025-05-06 7:25 ` Krzysztof Kozlowski
2025-05-07 23:16 ` Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 05/13] x86/dt: Parse the `enable-method` property of CPU nodes Ricardo Neri
2025-05-12 15:54 ` Rob Herring
2025-05-14 3:00 ` Ricardo Neri
2025-05-03 19:15 ` Ricardo Neri [this message]
2025-05-04 16:51 ` [PATCH v3 06/13] dt-bindings: reserved-memory: Wakeup Mailbox for Intel processors Krzysztof Kozlowski
2025-05-06 5:16 ` Ricardo Neri
2025-05-06 7:10 ` Krzysztof Kozlowski
2025-05-07 3:23 ` Ricardo Neri
2025-05-12 15:32 ` Rob Herring
2025-05-13 22:14 ` Ricardo Neri
2025-05-14 15:42 ` Rob Herring
2025-05-15 3:53 ` Ricardo Neri
2025-05-19 15:29 ` Rob Herring
2025-05-19 17:56 ` Ricardo Neri
2025-05-24 15:56 ` Ricardo Neri
2025-05-29 13:16 ` Rob Herring
2025-06-02 1:31 ` Ricardo Neri
2025-05-05 13:07 ` Rafael J. Wysocki
2025-05-06 5:50 ` Ricardo Neri
2025-05-06 14:00 ` Rafael J. Wysocki
2025-05-07 11:48 ` Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 07/13] x86/dt: Parse the " Ricardo Neri
2025-05-03 19:15 ` [PATCH v3 08/13] x86/hyperv/vtl: Set real_mode_header in hv_vtl_init_platform() Ricardo Neri
2025-05-20 1:24 ` Michael Kelley
2025-05-03 19:15 ` [PATCH v3 09/13] x86/realmode: Make the location of the trampoline configurable Ricardo Neri
2025-05-20 1:30 ` Michael Kelley
2025-05-03 19:15 ` [PATCH v3 10/13] x86/hyperv/vtl: Setup the 64-bit trampoline for TDX guests Ricardo Neri
2025-05-20 1:31 ` Michael Kelley
2025-05-03 19:15 ` [PATCH v3 11/13] x86/smpboot: Add a helper get the address of the wakeup mailbox Ricardo Neri
2025-05-20 1:32 ` Michael Kelley
2025-05-03 19:15 ` [PATCH v3 12/13] x86/hyperv/vtl: Mark the wakeup mailbox page as private Ricardo Neri
2025-05-20 1:33 ` Michael Kelley
2025-05-03 19:15 ` [PATCH v3 13/13] x86/hyperv/vtl: Use the wakeup mailbox to boot secondary CPUs Ricardo Neri
2025-05-20 1:35 ` Michael Kelley
2025-05-24 0:31 ` Ricardo Neri
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250503191515.24041-7-ricardo.neri-calderon@linux.intel.com \
--to=ricardo.neri-calderon@linux.intel.com \
--cc=cho@microsoft.com \
--cc=conor+dt@kernel.org \
--cc=decui@microsoft.com \
--cc=devicetree@vger.kernel.org \
--cc=haiyangz@microsoft.com \
--cc=kirill.shutemov@linux.intel.com \
--cc=krzk+dt@kernel.org \
--cc=kys@microsoft.com \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-hyperv@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mhklinux@outlook.com \
--cc=ravi.v.shankar@intel.com \
--cc=ricardo.neri@intel.com \
--cc=robh@kernel.org \
--cc=ssengar@linux.microsoft.com \
--cc=wei.liu@kernel.org \
--cc=x86@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®