On Mon, Sep 9, 2019 at 10:42 AM Andre Przywara <andre.przyw...@arm.com> wrote: > > On Wed, 28 Aug 2019 03:02:58 +0000 > Peng Fan <peng....@nxp.com> wrote: > > Hi, > > sorry for the late reply, eventually managed to have a closer look on this. > > > From: Peng Fan <peng....@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....@nxp.com> > > --- > > .../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: 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....@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? > > This maximum sounds rather arbitrary. Why do we need one? In the driver this > just allocates more memory, so why not just impose no artificial limit at all? > This will be gone, once the driver is converted to 1channel per controller.
> Actually, do we need this property at all? Can't we just rely on the size of > arm,func-ids to determine this (using of_property_count_elems_of_size() in > the driver)? Having both sounds redundant and brings up the question what to > do if they don't match. > > > + > > + method: > > + - enum: > > + - smc > > + - hvc > > + > > + transports: > > + - enum: > > + - mem > > + - reg > > Shouldn't there be a description on what both mean, exactly? > For instance I would expect a list of registers to be shown for the "reg" > case, and be it by referring to the ARM SMCCC. > > Also looking at the driver this brings up more questions: > - Which memory does mem refer to? If this is really the means of transport, > it should be referenced in this *controller* node and populated by the > driver. Looking at the example below and the driver code, it actually isn't > used that way, instead the memory is used and controlled by the mailbox > *client*. > - What is the actual difference between the two transports? For "mem" we just > populate the registers with 0, for "reg" we use the data. Couldn't this be > left to the client? > > There are more points which makes me think this property is actually > redundant, see my comments on patch 2/2. > > > + > > + 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. > > I think this makes it obvious that arm,num-chans is not needed. > > Also this somewhat contradicts the driver implementation, which allows the > array to be shorter, marking this as UINT_MAX and later on using the first > data item as a function identifier. This is somewhat surprising and not > documented (unless I missed something). > > So I would suggest: > - We drop the transports property, and always put the client provided data in > the registers, according to the SMCCC. Document this here. > A client not needing those could always puts zeros (or garbage) in there, > the respective firmware would just ignore the registers. > - We drop "arm,num-chans", as this is just redundant with the length of the > func-ids array. > - We don't impose an arbitrary limit on the number of channels. From the > firmware point of view this is just different function IDs, from Linux' point > of view just the size of the memory used. Both don't need to be limited > artificially IMHO. > Sounds like we are in sync. > - We mark arm,func-ids as required, as this needs to be fixed, allocated > number. > I still think func-id can be done without. A client can always pass the value as it knows what it expects. But I can live with it being optional. cheers!
