| Message ID | 1566942646-18015-2-git-send-email-peng.fan@nxp.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | mailbox: arm: introduce smc triggered mailbox | expand |
On Tue, Aug 27, 2019 at 4:51 AM Peng Fan <peng.fan@nxp.com> wrote: > > From: Peng Fan <peng.fan@nxp.com> > > The ARM SMC/HVC mailbox binding describes a firmware interface to trigger > actions in software layers running in the EL2 or EL3 exception levels. > The term "ARM" here relates to the SMC instruction as part of the ARM > instruction set, not as a standard endorsed by ARM Ltd. > > Signed-off-by: Peng Fan <peng.fan@nxp.com> > --- > .../devicetree/bindings/mailbox/arm-smc.yaml | 126 +++++++++++++++++++++ > 1 file changed, 126 insertions(+) > create mode 100644 Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > diff --git a/Documentation/devicetree/bindings/mailbox/arm-smc.yaml b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > new file mode 100644 > index 000000000000..ae677e0c0910 > --- /dev/null > +++ b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > @@ -0,0 +1,126 @@ > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/mailbox/arm-smc.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: ARM SMC Mailbox Interface > + > +maintainers: > + - Peng Fan <peng.fan@nxp.com> > + > +description: | > + This mailbox uses the ARM smc (secure monitor call) and hvc (hypervisor > + call) instruction to trigger a mailbox-connected activity in firmware, > + executing on the very same core as the caller. By nature this operation > + is synchronous and this mailbox provides no way for asynchronous messages > + to be delivered the other way round, from firmware to the OS, but > + asynchronous notification could also be supported. However the value of > + r0/w0/x0 the firmware returns after the smc call is delivered as a received > + message to the mailbox framework, so a synchronous communication can be > + established, for a asynchronous notification, no value will be returned. > + The exact meaning of both the action the mailbox triggers as well as the > + return value is defined by their users and is not subject to this binding. > + > + One use case of this mailbox is the SCMI interface, which uses shared memory > + to transfer commands and parameters, and a mailbox to trigger a function > + call. This allows SoCs without a separate management processor (or when > + such a processor is not available or used) to use this standardized > + interface anyway. > + > + This binding describes no hardware, but establishes a firmware interface. > + Upon receiving an SMC using one of the described SMC function identifiers, > + the firmware is expected to trigger some mailbox connected functionality. > + The communication follows the ARM SMC calling convention. > + Firmware expects an SMC function identifier in r0 or w0. The supported > + identifiers are passed from consumers, or listed in the the arm,func-ids > + properties as described below. The firmware can return one value in > + the first SMC result register, it is expected to be an error value, > + which shall be propagated to the mailbox client. > + > + Any core which supports the SMC or HVC instruction can be used, as long as > + a firmware component running in EL3 or EL2 is handling these calls. > + > +properties: > + compatible: > + const: arm,smc-mbox > + > + "#mbox-cells": > + const: 1 > + > + arm,num-chans: > + description: The number of channels supported. > + items: > + minimum: 1 > + maximum: 4096 # Should be enough? > + > + method: > + items: You can drop 'items' as this is a single entry. > + - enum: > + - smc > + - hvc > + > + transports: > + items: same here > + - enum: > + - mem > + - reg > + > + arm,func-ids: Needs a $ref to a type (uint32-array). > + description: | > + An array of 32-bit values specifying the function IDs used by each > + mailbox channel. Those function IDs follow the ARM SMC calling > + convention standard [1]. > + > + There is one identifier per channel and the number of supported > + channels is determined by the length of this array. > + minItems: 0 > + maxItems: 4096 # Should be enough? > + > +required: > + - compatible > + - "#mbox-cells" > + - arm,num-chans > + - transports > + - method > + > +examples: > + - | > + sram@910000 { > + compatible = "mmio-sram"; > + reg = <0x0 0x93f000 0x0 0x1000>; > + #address-cells = <1>; > + #size-cells = <1>; > + ranges = <0 0x0 0x93f000 0x1000>; > + > + cpu_scp_lpri: scp-shmem@0 { Looks like some indentation problem... > + compatible = "arm,scmi-shmem"; > + reg = <0x0 0x200>; > + }; > + > + cpu_scp_hpri: scp-shmem@200 { > + compatible = "arm,scmi-shmem"; > + reg = <0x200 0x200>; > + }; > + }; > + > + firmware { > + smc_mbox: mailbox { > + #mbox-cells = <1>; > + compatible = "arm,smc-mbox"; > + method = "smc"; > + arm,num-chans = <0x2>; > + transports = "mem"; > + /* Optional */ > + arm,func-ids = <0xc20000fe>, <0xc20000ff>; > + }; > + > + scmi { > + compatible = "arm,scmi"; > + mboxes = <&mailbox 0 &mailbox 1>; &smc_mbox and <> each entry. > + mbox-names = "tx", "rx"; > + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; <> each entry > + }; > + }; > + > +... > -- > 2.16.4 >
Hi Rob, > Subject: Re: [PATCH v4 1/2] dt-bindings: mailbox: add binding doc for the ARM > SMC/HVC mailbox > > On Tue, Aug 27, 2019 at 4:51 AM Peng Fan <peng.fan@nxp.com> wrote: > > > > From: Peng Fan <peng.fan@nxp.com> > > > > The ARM SMC/HVC mailbox binding describes a firmware interface to > > trigger actions in software layers running in the EL2 or EL3 exception levels. > > The term "ARM" here relates to the SMC instruction as part of the ARM > > instruction set, not as a standard endorsed by ARM Ltd. > > > > Signed-off-by: Peng Fan <peng.fan@nxp.com> > > --- > > .../devicetree/bindings/mailbox/arm-smc.yaml | 126 > +++++++++++++++++++++ > > 1 file changed, 126 insertions(+) > > create mode 100644 > > Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > > > diff --git a/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > new file mode 100644 > > index 000000000000..ae677e0c0910 > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > @@ -0,0 +1,126 @@ > > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 > > +--- > > +$id: > > +https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevi > > > +cetree.org%2Fschemas%2Fmailbox%2Farm-smc.yaml%23&data=02%7 > C01%7Cp > > > +eng.fan%40nxp.com%7C0e905f3fe89b4dc9ee0608d72af06e30%7C686ea1d > 3bc2b4c > > > +6fa92cd99c5c301635%7C0%7C0%7C637025084458964761&sdata=p8 > EeFkU5pW3 > > +D8bzpZu9IHCoFD%2F2ZBcSr6WyCsIK9LqU%3D&reserved=0 > > +$schema: > > +https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdevi > > > +cetree.org%2Fmeta-schemas%2Fcore.yaml%23&data=02%7C01%7Cpe > ng.fan% > > > +40nxp.com%7C0e905f3fe89b4dc9ee0608d72af06e30%7C686ea1d3bc2b4c6 > fa92cd9 > > > +9c5c301635%7C0%7C0%7C637025084458964761&sdata=JFhz7meFyG > ozMLnt4Jb > > +RGneYty6cBSCKyxHpl26TAsI%3D&reserved=0 > > + > > +title: ARM SMC Mailbox Interface > > + > > +maintainers: > > + - Peng Fan <peng.fan@nxp.com> > > + > > +description: | > > + This mailbox uses the ARM smc (secure monitor call) and hvc > > +(hypervisor > > + call) instruction to trigger a mailbox-connected activity in > > +firmware, > > + executing on the very same core as the caller. By nature this > > +operation > > + is synchronous and this mailbox provides no way for asynchronous > > +messages > > + to be delivered the other way round, from firmware to the OS, but > > + asynchronous notification could also be supported. However the > > +value of > > + r0/w0/x0 the firmware returns after the smc call is delivered as a > > +received > > + message to the mailbox framework, so a synchronous communication > > +can be > > + established, for a asynchronous notification, no value will be returned. > > + The exact meaning of both the action the mailbox triggers as well > > +as the > > + return value is defined by their users and is not subject to this binding. > > + > > + One use case of this mailbox is the SCMI interface, which uses > > + shared memory to transfer commands and parameters, and a mailbox > to > > + trigger a function call. This allows SoCs without a separate > > + management processor (or when such a processor is not available or > > + used) to use this standardized interface anyway. > > + > > + This binding describes no hardware, but establishes a firmware > interface. > > + Upon receiving an SMC using one of the described SMC function > > + identifiers, the firmware is expected to trigger some mailbox connected > functionality. > > + The communication follows the ARM SMC calling convention. > > + Firmware expects an SMC function identifier in r0 or w0. The > > + supported identifiers are passed from consumers, or listed in the > > + the arm,func-ids properties as described below. The firmware can > > + return one value in the first SMC result register, it is expected > > + to be an error value, which shall be propagated to the mailbox client. > > + > > + Any core which supports the SMC or HVC instruction can be used, as > > + long as a firmware component running in EL3 or EL2 is handling these > calls. > > + > > +properties: > > + compatible: > > + const: arm,smc-mbox > > + > > + "#mbox-cells": > > + const: 1 > > + > > + arm,num-chans: > > + description: The number of channels supported. > > + items: > > + minimum: 1 > > + maximum: 4096 # Should be enough? > > + > > + method: > > + items: > > You can drop 'items' as this is a single entry. Will fix in v5. > > > + - enum: > > + - smc > > + - hvc > > + > > + transports: > > + items: > > same here Fix in v5. > > > + - enum: > > + - mem > > + - reg > > + > > + arm,func-ids: > > Needs a $ref to a type (uint32-array). Fix in v5. > > > + description: | > > + An array of 32-bit values specifying the function IDs used by each > > + mailbox channel. Those function IDs follow the ARM SMC calling > > + convention standard [1]. > > + > > + There is one identifier per channel and the number of supported > > + channels is determined by the length of this array. > > + minItems: 0 > > + maxItems: 4096 # Should be enough? > > + > > +required: > > + - compatible > > + - "#mbox-cells" > > + - arm,num-chans > > + - transports > > + - method > > + > > +examples: > > + - | > > + sram@910000 { > > + compatible = "mmio-sram"; > > + reg = <0x0 0x93f000 0x0 0x1000>; > > + #address-cells = <1>; > > + #size-cells = <1>; > > + ranges = <0 0x0 0x93f000 0x1000>; > > + > > + cpu_scp_lpri: scp-shmem@0 { > > Looks like some indentation problem... Fix in v5. > > > + compatible = "arm,scmi-shmem"; > > + reg = <0x0 0x200>; > > + }; > > + > > + cpu_scp_hpri: scp-shmem@200 { > > + compatible = "arm,scmi-shmem"; > > + reg = <0x200 0x200>; > > + }; > > + }; > > + > > + firmware { > > + smc_mbox: mailbox { > > + #mbox-cells = <1>; > > + compatible = "arm,smc-mbox"; > > + method = "smc"; > > + arm,num-chans = <0x2>; > > + transports = "mem"; > > + /* Optional */ > > + arm,func-ids = <0xc20000fe>, <0xc20000ff>; > > + }; > > + > > + scmi { > > + compatible = "arm,scmi"; > > + mboxes = <&mailbox 0 &mailbox 1>; > > &smc_mbox and <> each entry. Fix in v5. > > > + mbox-names = "tx", "rx"; > > + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; > > <> each entry Fix in v5. Thanks, Peng. > > > + }; > > + }; > > + > > +... > > -- > > 2.16.4 > >
diff --git a/Documentation/devicetree/bindings/mailbox/arm-smc.yaml b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml new file mode 100644 index 000000000000..ae677e0c0910 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mailbox/arm-smc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM SMC Mailbox Interface + +maintainers: + - Peng Fan <peng.fan@nxp.com> + +description: | + This mailbox uses the ARM smc (secure monitor call) and hvc (hypervisor + call) instruction to trigger a mailbox-connected activity in firmware, + executing on the very same core as the caller. By nature this operation + is synchronous and this mailbox provides no way for asynchronous messages + to be delivered the other way round, from firmware to the OS, but + asynchronous notification could also be supported. However the value of + r0/w0/x0 the firmware returns after the smc call is delivered as a received + message to the mailbox framework, so a synchronous communication can be + established, for a asynchronous notification, no value will be returned. + The exact meaning of both the action the mailbox triggers as well as the + return value is defined by their users and is not subject to this binding. + + One use case of this mailbox is the SCMI interface, which uses shared memory + to transfer commands and parameters, and a mailbox to trigger a function + call. This allows SoCs without a separate management processor (or when + such a processor is not available or used) to use this standardized + interface anyway. + + This binding describes no hardware, but establishes a firmware interface. + Upon receiving an SMC using one of the described SMC function identifiers, + the firmware is expected to trigger some mailbox connected functionality. + The communication follows the ARM SMC calling convention. + Firmware expects an SMC function identifier in r0 or w0. The supported + identifiers are passed from consumers, or listed in the the arm,func-ids + properties as described below. The firmware can return one value in + the first SMC result register, it is expected to be an error value, + which shall be propagated to the mailbox client. + + Any core which supports the SMC or HVC instruction can be used, as long as + a firmware component running in EL3 or EL2 is handling these calls. + +properties: + compatible: + const: arm,smc-mbox + + "#mbox-cells": + const: 1 + + arm,num-chans: + description: The number of channels supported. + items: + minimum: 1 + maximum: 4096 # Should be enough? + + method: + items: + - enum: + - smc + - hvc + + transports: + items: + - enum: + - mem + - reg + + arm,func-ids: + description: | + An array of 32-bit values specifying the function IDs used by each + mailbox channel. Those function IDs follow the ARM SMC calling + convention standard [1]. + + There is one identifier per channel and the number of supported + channels is determined by the length of this array. + minItems: 0 + maxItems: 4096 # Should be enough? + +required: + - compatible + - "#mbox-cells" + - arm,num-chans + - transports + - method + +examples: + - | + sram@910000 { + compatible = "mmio-sram"; + reg = <0x0 0x93f000 0x0 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x0 0x93f000 0x1000>; + + cpu_scp_lpri: scp-shmem@0 { + compatible = "arm,scmi-shmem"; + reg = <0x0 0x200>; + }; + + cpu_scp_hpri: scp-shmem@200 { + compatible = "arm,scmi-shmem"; + reg = <0x200 0x200>; + }; + }; + + firmware { + smc_mbox: mailbox { + #mbox-cells = <1>; + compatible = "arm,smc-mbox"; + method = "smc"; + arm,num-chans = <0x2>; + transports = "mem"; + /* Optional */ + arm,func-ids = <0xc20000fe>, <0xc20000ff>; + }; + + scmi { + compatible = "arm,scmi"; + mboxes = <&mailbox 0 &mailbox 1>; + mbox-names = "tx", "rx"; + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; + }; + }; + +...