// SPDX-License-Identifier: GPL-2.0
/*
* System Control and Management Interface (SCMI) Raw mode support
*
* Copyright (C) 2022 ARM Ltd.
*/
/**
* DOC: Theory of operation
*
* When enabled the SCMI Raw mode support exposes a userspace API which allows
* to send and receive SCMI commands, replies and notifications from a user
* application through injection and snooping of bare SCMI messages in binary
* little-endian format.
*
* Such injected SCMI transactions will then be routed through the SCMI core
* stack towards the SCMI backend server using whatever SCMI transport is
* currently configured on the system under test.
*
* It is meant to help in running any sort of SCMI backend server testing, no
* matter where the server is placed, as long as it is normally reachable via
* the transport configured on the system.
*
* It is activated by a Kernel configuration option since it is NOT meant to
* be used in production but only during development and in CI deployments.
*
* In order to avoid possible interferences between the SCMI Raw transactions
* originated from a test-suite and the normal operations of the SCMI drivers,
* when Raw mode is enabled, by default, all the regular SCMI drivers are
* inhibited, unless CONFIG_ARM_SCMI_RAW_MODE_SUPPORT_COEX is enabled: in this
* latter case the regular SCMI stack drivers will be loaded as usual and it is
* up to the user of this interface to take care of manually inhibiting the
* regular SCMI drivers in order to avoid interferences during the test runs.
*
* The exposed API is as follows.
*
* All SCMI Raw entries are rooted under a common top /raw debugfs top directory
* which in turn is rooted under the corresponding underlying SCMI instance.
*
* /sys/kernel/debug/scmi/
* `-- 0
* |-- atomic_threshold_us
* |-- instance_name
* |-- raw
* | |-- channels
* | | |-- 0x10
* | | | |-- message
* | | | `-- message_async
* | | `-- 0x13
* | | |-- message
* | | `-- message_async
* | |-- errors
* | |-- message
* | |-- message_async
* | |-- notification
* | `-- reset
* `-- transport
* |-- is_atomic
* |-- max_msg_size
* |-- max_rx_timeout_ms
* |-- rx_max_msg
* |-- tx_max_msg
* `-- type
*
* where:
*
* - errors: used to read back timed-out and unexpected replies
* - message*: used to send sync/async commands and read back immediate and
* delayed reponses (if any)
* - notification: used to read any notification being emitted by the system
* (if previously enabled by the user app)
* - reset: used to flush the queues of messages (of any kind) still pending
* to be read; this is useful at test-suite start/stop to get
* rid of any unread messages from the previous run.
*
* with the per-channel entries rooted at /channels being present only on a
* system where multiple transport channels have been configured.
*
* Such per-channel entries can be used to explicitly choose a specific channel
* for SCMI bare message injection, in contrast with the general entries above
* where, instead, the selection of the proper channel to use is automatically
* performed based the protocol embedded in the injected message and on how the
* transport is configured on the system.
*
* Note that other common general entries are available under transport/ to let
* the user applications properly make up their expectations in terms of
* timeouts and message characteristics.
*
* Each write to the message* entries causes one command request to be built
* and sent while the replies or delayed response are read back from those same
* entries one message at time (receiving an EOF at each message boundary).
*
* The user application running the test is in charge of handling timeouts
* on replies and properly choosing SCMI sequence numbers for the outgoing
* requests (using the same sequence number is supported but discouraged).
*