> Subject: Re: [PATCH v5 1/2] dt-bindings: mailbox: add binding doc for the ARM > SMC/HVC mailbox > > On Wed, Aug 28, 2019 at 03:02:58AM +0000, Peng Fan wrote: > > From: Peng Fan <peng.fan@xxxxxxx> > > > > 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@xxxxxxx> > > --- > > .../devicetree/bindings/mailbox/arm-smc.yaml | 125 > +++++++++++++++++++++ > > 1 file changed, 125 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..f8eb28d5e307 > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/mailbox/arm-smc.yaml > > @@ -0,0 +1,125 @@ > > +# 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%7C37aa729c94944730868b08d72bbfc121%7C686ea1 > d3bc2b4c > > > +6fa92cd99c5c301635%7C0%7C1%7C637025974936865698&sdata=Inp > %2FLs39m > > +Gv1fe3dZMSaGmgmyWPT6awPh47s3mEtQ%2BQ%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%7C37aa729c94944730868b08d72bbfc121%7C686ea1d3bc2b4c > 6fa92cd9 > > > +9c5c301635%7C0%7C1%7C637025974936865698&sdata=jmoR1Qqm7 > 6N5NwDbgFE > > +Fm8cpdW%2B%2FgqmG9mSGz9mXv58%3D&reserved=0 > > + > > +title: ARM SMC Mailbox Interface > > + > > +maintainers: > > + - Peng Fan <peng.fan@xxxxxxx> > > + > > +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. > > What do you mean by that ? I would prefer to drop the above line unless I am Ok. Dropped it in v6. > missing something. IMO it contradicts the previous statement less you > elaborate more on this. > > > 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. > > I assume you refer to asynchronous communication from OS to firmware in > the above statement and "not asynchronous notification" from firmware to > OS. Since asynchronous notification dropped, so it should only be synchronous communication could be established. So I'll modify it as below: r0/w0/x0 the firmware returns after the smc call is delivered as a received message to the mailbox framework, so synchronous communication can be established > > > + 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. > > + > > Not sure if reference to SCMI is needed at all but I don't have any objections > to it, just thought worth mentioning. > > > + 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. > > + > > > Other than the above points, I am fine with it. Once fixed, > > Reviewed-by: Sudeep Holla <sudeep.holla@xxxxxxx> Thanks, Peng. > > Note I haven't reviewed the yaml scheme, but just binding in general. > > -- > Regards, > Sudeep
