RE: [PATCH 3/5] firmware: arm_scmi: imx: Add LMM and CPU documentation

Peng Fan
2025-01-23T01:30:46Z

Hi Sudeep,

> Subject: Re: [PATCH 3/5] firmware: arm_scmi: imx: Add LMM and CPU
> documentation
>
> On Tue, Jan 21, 2025 at 11:08:13PM +0800, Peng Fan (OSS) wrote:
> > From: Peng Fan <peng.fan@nxp.com>
> >
> > Add i.MX95 Logical Machine Management and CPU Protocol
> documentation.
> >
>
> Please make this the first patch when you need to respin this(which is
> clearly not yet 😁)

Sure.

>
> > Signed-off-by: Peng Fan <peng.fan@nxp.com>
> > ---
> > drivers/firmware/arm_scmi/vendors/imx/imx95.rst | 692
> > ++++++++++++++++++++++++
> > 1 file changed, 692 insertions(+)
> >
> > diff --git a/drivers/firmware/arm_scmi/vendors/imx/imx95.rst
> > b/drivers/firmware/arm_scmi/vendors/imx/imx95.rst
> > index
> >
> b2dfd6c46ca2f5f12f0475c24cb54c060e9fa421..384d4f9c27e489a9c5
> 4cdde79c9f
> > 03a6f5979630 100644
> > --- a/drivers/firmware/arm_scmi/vendors/imx/imx95.rst
> > +++ b/drivers/firmware/arm_scmi/vendors/imx/imx95.rst
> > @@ -32,6 +32,419 @@ port, and deploy the SM on supported
> processors.
> > The SM implements an interface compliant with the Arm SCMI
> > Specification with additional vendor specific extensions.
> >
> > +SCMI_LMM: System Control and Management Logical Machine
> Management
> > +Vendor Protocol
> >
> +===========================================================
> ==========
> > +=============
> > +
> > +This protocol is intended for boot, shutdown, and reset of other
> > +logical machines (LM). It is usually used to allow one LM to manager
> > +another used as an offload or accelerator engine.
>
> The above statement is very hard to parse. Can it be "
> It is usually used to allow one LM(e.g. OSPM) to manage another LM
> which is usually an offload or accelerator engine.
> "
> if I understood it correctly ?

Correct. I will update.

>
> > Notifications from this protocol can
> > +also be used to manage a communication link to another LM. The
> LMM
> > +protocol provides functions to:
> > +
> > +- Describe the protocol version.
> > +- Discover implementation attributes.
> > +- Discover the LMs defined in the system.
> > +- Boot an LM.
> > +- Shut down an LM.
> > +- Reset an LM.
> > +- Wake an LM from suspend.
> > +- Suspend an LM (gracefully).
> > +- Request a graceful shutdown or reset of an LM.
>
> Does that mean above "Shut down an LM" and "Reset an LM" are
> forced ones ?

No. Both supports graceful feature.

Forced ones means the System Manager will force shutdown or reset a
LM.

Graceful ones means System Manager will send notification to one LM,
the LM will shutdown or reset itself.

>
> > +- Allow an agent to forcibly power down or reset an LM.
>
> How is this different from the above ?

The above says gracefully shutdown or reset.
Here says forcibly.

Say above about gracefully and forcibly.

>
> > +- Read boot/shutdown/reset information for an LM.
> > +- Get notifications when an LM boots or shuts down.
> > +
> > +Commands:
> > +_________
> > +
> > +PROTOCOL_VERSION
> > +~~~~~~~~~~~~~~~~
> > +
> > +message_id: 0x0
> > +protocol_id: 0x80
> > +
> > ++---------------+--------------------------------------------------------------+
> > +|Return values |
> > ++---------------+--------------------------------------------------------------+
> > +|Name |Description |
> > ++---------------+--------------------------------------------------------------+
> > +|int32 status | See ARM SCMI Specification for status code
> definitions. |
> > ++---------------+--------------------------------------------------------------+
> > +|uint32 version | For this revision of the specification, this value
> must be |
> > +| | 0x10000. |
> > ++---------------+--------------------------------------------------------------+
> > +
> > +PROTOCOL_ATTRIBUTES
> > +~~~~~~~~~~~~~~~~~~~
> > +
> > +message_id: 0x1
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status | See ARM SCMI Specification for status code
> definitions. |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 attributes |Protocol attributes: |
> > +| |Bits[31:8] Reserved, must be zero. |
> > +| |Bits[7:0] Number of Logical Machines |
> > ++------------------+-----------------------------------------------------------+
> > +
> > +PROTOCOL_MESSAGE_ATTRIBUTES
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +message_id: 0x2
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: in case the message is implemented and
> available |
> > +| |to use. |
> > +| |NOT_FOUND: if the message identified by message_id
> is |
> > +| |invalid or not implemented |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 attributes |Flags that are associated with a specific function
> in the |
> > +| |protocol. For all functions in this protocol, this |
> > +| |parameter has a value of 0 |
> > ++------------------+-----------------------------------------------------------+
> > +
> > +LMM_ATTRIBUTES
> > +~~~~~~~~~~~~~~
> > +
> > +message_id: 0x3
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
>
> Where are the actual attributes returned ?

Oh. This was missed. It will return the LM state, name, errstate.

>
> > +|int32 status |SUCCESS: if valid attributes are returned.
> |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |DENIED: if the agent does not have permission to get
> info |
> > +| |for the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
> > +LMM_BOOT
> > +~~~~~~~~
> > +
> > +message_id: 0x4
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully booted.
> |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
>
> Is this synchronous boot ? When will the notifications be used then ?

Yes. Sync boot. After the System Manager boots the LM, the System
Manager will send notification to subscribers.

>
> > +LMM_RESET
> > +~~~~~~~~~
> > +
> > +message_id: 0x5
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 flags |Reset flags: |
> > +| |Bits[31:1] Reserved, must be zero. |
> > +| |Bit[0] Graceful request: |
> > +| |Set to 1 if the request is a graceful request. |
> > +| |Set to 0 if the request is a forceful request. |
>
>
> Ah so you have flag here then. I wonder why you need separate
> command then ?

Sorry. I not follow you here.

LMM_Shutdown/LMM_Reset/LMM_DoBoot are the commands
to shutdown/reset/boot one LM.

>
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully resets. |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
>
> Again, is this done synchronously ?

If flag is set graceful, the LM will reset itself, so sync reset from
LM view.
If flag is forced ones, the LM will be forced reset, so async reset
from LM view.

>
> > +LMM_SHUTDOWN
> > +~~~~~~~~~~~~
> > +
> > +message_id: 0x6
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 flags |Reset flags: |
> > +| |Bits[31:1] Reserved, must be zero. |
> > +| |Bit[0] Graceful request: |
> > +| |Set to 1 if the request is a graceful request. |
> > +| |Set to 0 if the request is a forceful request. |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully shutdowns.
> |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
>
> Ditto, sync ?

Same as above LMM_Reset.

>
> > +LMM_WAKE
> > +~~~~~~~~
> > +
> > +message_id: 0x7
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully wakes. |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
>
> Ditto, sync ?

This is sync. Saying LM is in suspend state, one LM could wake other
LM if permission allowed.

>
> > +LMM_SUSPEND
> > +~~~~~~~~~~~
> > +
> > +message_id: 0x8
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully suspends.
> |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
>
> Ditto, sync ?

Yes. Sync. The LM need suspend itself, SM will send notification to LM.

>
> > +LMM_NOTIFY
> > +~~~~~~~~~~
> > +
> > +message_id: 0x9
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 flags |Notification flags: |
> > +| |Bits[31:3] Reserved, must be zero. |
> > +| |Bit[3] Wake (resume) notification: |
> > +| |Set to 1 to send notification. |
> > +| |Set to 0 if no notification. |
> > +| |Bit[2] Suspend (sleep) notification: |
> > +| |Set to 1 to send notification. |
> > +| |Set to 0 if no notification. |
> > +| |Bit[1] Shutdown (off) notification: |
> > +| |Set to 1 to send notification. |
> > +| |Set to 0 if no notification. |
> > +| |Bit[0] Boot (on) notification: |
> > +| |Set to 1 to send notification. |
> > +| |Set to 0 if no notification |
>
> How about reset ?

The LMM will also send System power management notification.
Reset will use it.

>
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if the notification state successfully
> updated. |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if input attributes flag specifies
> |
> > +| |unsupported or invalid configurations. |
> > +| |DENIED: if the agent does not have permission to
> request |
> > +| |the notification. |
> > ++------------------+-----------------------------------------------------------+
> > +
> > +LMM_RESET_REASON
> > +~~~~~~~~~~~~~~~~
> > +
> > +message_id: 0xA
> > +protocol_id: 0x80
> > +
> > ++---------------------+--------------------------------------------------------+
> > +|Parameters |
> > ++---------------------+--------------------------------------------------------+
> > +|Name |Description |
> > ++---------------------+--------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++---------------------+--------------------------------------------------------+
> > +|Return values |
> > ++---------------------+--------------------------------------------------------+
> > +|Name |Description |
> > ++---------------------+--------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully suspends.
> |
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine|
> > +| |DENIED: if the agent does not have permission to
> request|
> > +| |the reset reason. |
> > ++---------------------+--------------------------------------------------------+
> > +|uint32 bootflags |Boot reason flags. This parameter has the
> format: |
> > +| |Bits[31] Valid. |
> > +| |Set to 1 if the entire reason is valid. |
> > +| |Set to 0 if the entire reason is not valid. |
> > +| |Bits[30:29] Reserved, must be zero. |
> > +| |Bit[28] Valid origin: |
>
> Valid with origin ID perhaps ?

No. This is from SM Doc, it is valid origin, saying valid source.

>
> > +| |Set to 1 if the origin field is valid. |
> > +| |Set to 0 if the origin field is not valid. |
> > +| |Bits[27:24] Origin. |
> > +| |Bit[23] Valid err ID: |
> > +| |Set to 1 if the error ID field is valid. |
> > +| |Set to 0 if the error ID field is not valid. |
> > +| |Bits[22:8] Error ID. |
> > +| |Bit[7:0] Reason |
>
> Reasons definitions are Platform specific ?

Yes. This info is from SOC system reset controller, such as WDOG,
JTAG, POR and etc.

>
> > ++---------------------+--------------------------------------------------------+
> > +|uint32 shutdownflags |Shutdown reason flags. This parameter has
> the format: |
> > +| |Bits[31] Valid. |
> > +| |Set to 1 if the entire reason is valid. |
> > +| |Set to 0 if the entire reason is not valid. |
> > +| |Bits[30:29] Number of valid extended info words.
> |
> > +| |Bit[28] Valid origin: |
> > +| |Set to 1 if the origin field is valid. |
> > +| |Set to 0 if the origin field is not valid. |
> > +| |Bits[27:24] Origin. |
> > +| |Bit[23] Valid err ID: |
> > +| |Set to 1 if the error ID field is valid. |
> > +| |Set to 0 if the error ID field is not valid. |
> > +| |Bits[22:8] Error ID. |
> > +| |Bit[7:0] Reason |
>
> Again nothing for reset ? Do you expect reset to be forceful shutdown
> and boot in which case both the above are set ?

The reset implementation is actually first shutdown, then boot.
I loop our System Manager Owner to help answer. In case My answer is
not correct.

>
> > ++---------------------+--------------------------------------------------------+
> > +|uint32 extinfo[0,20] |Array of extended info words
> |
>
> What are these ?

It depends, such as pmic fault flags, fault pc.

>
> > ++---------------------+--------------------------------------------------------+
> > +
> > +LMM_POWER_ON
> > +~~~~~~~~~~~~
> > +
> > +message_id: 0xB
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |ID of the Logical Machine |
> > ++------------------+-----------------------------------------------------------+
> > +|Return values |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|int32 status |SUCCESS: if LM successfully suspends.
> |
>
> /me confused. Is it suspend(which is already defined) ? Or reset(again
> already
> defined) ?

Sorry. This should be power on.

>
> > +| |NOT_FOUND: if lmId not points to a valid logical
> machine. |
> > +| |INVALID_PARAMETERS: if lmId is same as the caller.
> |
> > +| |DENIED: if the agent does not have permission to
> manage the|
> > +| |the LM specified by lmid. |
> > ++------------------+-----------------------------------------------------------+
> > +
> > +NEGOTIATE_PROTOCOL_VERSION
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +message_id: 0x10
> > +protocol_id: 0x80
> > +
> > ++--------------------+---------------------------------------------------------+
> > +|Parameters |
> > ++--------------------+---------------------------------------------------------+
> > +|Name |Description |
> > ++--------------------+---------------------------------------------------------+
> > +|uint32 version |The negotiated protocol version the agent
> intends to use |
> > ++--------------------+---------------------------------------------------------+
> > +|Return values |
> > ++--------------------+---------------------------------------------------------+
> > +|Name |Description |
> > ++--------------------+---------------------------------------------------------+
> > +|int32 status |SUCCESS: if the negotiated protocol version is
> supported |
> > +| |by the platform. All commands, responses, and
> |
> > +| |notifications post successful return of this command
> must|
> > +| |comply with the negotiated version. |
> > +| |NOT_SUPPORTED: if the protocol version is not
> > +|supported. |
> > ++--------------------+---------------------------------------------------------+
> > +
> > +Notifications
> > +_____________
> > +
> > +LMM_EVENT
> > +~~~~~~~~~
> > +
> > +message_id: 0x0
> > +protocol_id: 0x80
> > +
> > ++------------------+-----------------------------------------------------------+
> > +|Parameters |
> > ++------------------+-----------------------------------------------------------+
> > +|Name |Description |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 lmid |Identifier for the LM that caused the transition.
> |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 eventlm |Identifier for the LM the event is for.
> |
> > ++------------------+-----------------------------------------------------------+
> > +|uint32 flags |LM events: |
> > +| |Bits[31:3] Reserved, must be zero. |
> > +| |Bit[3] Wake (resume) event: |
> > +| |1 LM has awakened. |
> > +| |0 not a wake event. |
> > +| |Bit[2] Suspend (sleep) event: |
> > +| |1 LM has suspended. |
> > +| |0 not a suspend event. |
> > +| |Bit[1] Shutdown (off) event: |
> > +| |1 LM has shutdown. |
> > +| |0 not a shutdown event. |
> > +| |Bit[0] Boot (on) event: |
> > +| |1 LM has booted. |
> > +| |0 not a boot event. |
> > ++------------------+-----------------------------------------------------------+
> > +
> > SCMI_BBM: System Control and Management BBM Vendor Protocol
> >
> ============================================================
> ==
> >
> > @@ -436,6 +849,285 @@ protocol_id: 0x81
> > | |0 no button change detected. |
> >
> > +------------------+--------------------------------------------------
> > ---------+
> >
> > +SCMI_CPU: System Control and Management CPU Vendor Protocol
> >
> +===========================================================
> ===
> > +
> > +This protocol allows an agent to start or stop a CPU. It is used to
> > +manage auxiliary CPUs in an LM (e.g. additional cores in an AP
> > +cluster), The CPU protocol provides functions to:
> > +
>
> Additional CPU in AP cluster ? That sounds alarming. Why not use PSCI ?

This is to manage the M7 core by Linux. I just put more documentation here.
CPU protocol is also used by ATF to manage AP cores.

> Also what other CPUs are we talking here.

M7 core

In general I would like to
> explore the possibility of collapsing this with LM protocol. CPUs within
> LM is LM's responsibility to bring up. And CPU can be seen as an LM for
> sake of this vendor protocol. I am not get into details here yet before I
> can understand what these CPUs are really in the system and why we
> need this.

Our system supports M7 and A55 in one LM, so A55 use CPU protocol to
manage M7. When M7 and A55 in different LM, use LM protocol to
manage M7 LM.

Thanks,
Peng.

>
> --
> Regards,
> Sudeep