refactor(smccc): move debugfs to vendor el3 calls
Move debugfs to Vendor-Specific EL3 Monitor Service Calls.
Function Identifier for Vendor-Specific EL3 Monitor Service is '7' and
allocated subranges of Function identifiers to different services are:
0x87000000-0x8700FFFF-SMC32: Vendor-Specific EL3 Monitor Service Calls
0xC7000000-0xC700FFFF-SMC64: Vendor-Specific EL3 Monitor Service Calls
Amend Debugfs FID's to use this range and id.
Add a deprecation notice to inform debugfs moved from arm-sip range to
Vendor-Specific EL3 range. Debugfs support from arm-sip range will be
removed and will not be available after TF-A 2.12 release.
Reference to debugfs component level documentation:
https://trustedfirmware-a.readthedocs.io/en/latest/components/debugfs-design.html#overview
Change-Id: I97a50170178f361f70c95ed0049bc4e278de59d7
Signed-off-by: Govindraj Raja <govindraj.raja@arm.com>
diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst
index b51a94d..9bbedb0 100644
--- a/docs/components/arm-sip-service.rst
+++ b/docs/components/arm-sip-service.rst
@@ -17,7 +17,6 @@
- Performance Measurement Framework (PMF)
- Execution State Switching service
-- DebugFS interface
Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header
file.
@@ -88,348 +87,8 @@
and 1 populated with the supplied *Cookie hi* and *Cookie lo* values,
respectively.
-DebugFS interface
------------------
-
-The optional DebugFS interface is accessed through an SMC SiP service. Refer
-to the component documentation for details.
-
-String parameters are passed through a shared buffer using a specific union:
-
-.. code:: c
-
- union debugfs_parms {
- struct {
- char fname[MAX_PATH_LEN];
- } open;
-
- struct mount {
- char srv[MAX_PATH_LEN];
- char where[MAX_PATH_LEN];
- char spec[MAX_PATH_LEN];
- } mount;
-
- struct {
- char path[MAX_PATH_LEN];
- dir_t dir;
- } stat;
-
- struct {
- char oldpath[MAX_PATH_LEN];
- char newpath[MAX_PATH_LEN];
- } bind;
- };
-
-Format of the dir_t structure as such:
-
-.. code:: c
-
- typedef struct {
- char name[NAMELEN];
- long length;
- unsigned char mode;
- unsigned char index;
- unsigned char dev;
- qid_t qid;
- } dir_t;
-
-
-* Identifiers
-
-======================== =============================================
-SMC_OK 0
-SMC_UNK -1
-DEBUGFS_E_INVALID_PARAMS -2
-======================== =============================================
-
-======================== =============================================
-MOUNT 0
-CREATE 1
-OPEN 2
-CLOSE 3
-READ 4
-WRITE 5
-SEEK 6
-BIND 7
-STAT 8
-INIT 10
-VERSION 11
-======================== =============================================
-
-MOUNT
-~~~~~
-
-Description
-^^^^^^^^^^^
-This operation mounts a blob of data pointed to by path stored in `src`, at
-filesystem location pointed to by path stored in `where`, using driver pointed
-to by path in `spec`.
-
-Parameters
-^^^^^^^^^^
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``MOUNT``
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if mount operation failed
-=============== ==========================================================
-
-OPEN
-~~~~
-
-Description
-^^^^^^^^^^^
-This operation opens the file path pointed to by `fname`.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``OPEN``
-uint32_t mode
-======== ============================================================
-
-mode can be one of:
-
-.. code:: c
-
- enum mode {
- O_READ = 1 << 0,
- O_WRITE = 1 << 1,
- O_RDWR = 1 << 2,
- O_BIND = 1 << 3,
- O_DIR = 1 << 4,
- O_STAT = 1 << 5
- };
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if open operation failed
-
-uint32_t w1: file descriptor id on success.
-=============== ==========================================================
-
-CLOSE
-~~~~~
-
-Description
-^^^^^^^^^^^
-
-This operation closes a file described by a file descriptor obtained by a
-previous call to OPEN.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``CLOSE``
-uint32_t File descriptor id returned by OPEN
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if close operation failed
-=============== ==========================================================
-
-READ
-~~~~
-
-Description
-^^^^^^^^^^^
-
-This operation reads a number of bytes from a file descriptor obtained by
-a previous call to OPEN.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``READ``
-uint32_t File descriptor id returned by OPEN
-uint32_t Number of bytes to read
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-On success, the read data is retrieved from the shared buffer after the
-operation.
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if read operation failed
-
-uint32_t w1: number of bytes read on success.
-=============== ==========================================================
-
-SEEK
-~~~~
-
-Description
-^^^^^^^^^^^
-
-Move file pointer for file described by given `file descriptor` of given
-`offset` related to `whence`.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``SEEK``
-uint32_t File descriptor id returned by OPEN
-sint32_t offset in the file relative to whence
-uint32_t whence
-======== ============================================================
-
-whence can be one of:
-
-========= ============================================================
-KSEEK_SET 0
-KSEEK_CUR 1
-KSEEK_END 2
-========= ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if seek operation failed
-=============== ==========================================================
-
-BIND
-~~~~
-
-Description
-^^^^^^^^^^^
-
-Create a link from `oldpath` to `newpath`.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``BIND``
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if bind operation failed
-=============== ==========================================================
-
-STAT
-~~~~
-
-Description
-^^^^^^^^^^^
-
-Perform a stat operation on provided file `name` and returns the directory
-entry statistics into `dir`.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``STAT``
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ==========================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if stat operation failed
-=============== ==========================================================
-
-INIT
-~~~~
-
-Description
-^^^^^^^^^^^
-Initial call to setup the shared exchange buffer. Notice if successful once,
-subsequent calls fail after a first initialization. The caller maps the same
-page frame in its virtual space and uses this buffer to exchange string
-parameters with filesystem primitives.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``INIT``
-uint64_t Physical address of the shared buffer.
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ======================================================
-int32_t w0 == SMC_OK on success
-
- w0 == DEBUGFS_E_INVALID_PARAMS if already initialized,
- or internal error occurred.
-=============== ======================================================
-
-VERSION
-~~~~~~~
-
-Description
-^^^^^^^^^^^
-Returns the debugfs interface version if implemented in TF-A.
-
-Parameters
-^^^^^^^^^^
-
-======== ============================================================
-uint32_t FunctionID (0x82000030 / 0xC2000030)
-uint32_t ``VERSION``
-======== ============================================================
-
-Return values
-^^^^^^^^^^^^^
-
-=============== ======================================================
-int32_t w0 == SMC_OK on success
-
- w0 == SMC_UNK if interface is not implemented
-
-uint32_t w1: On success, debugfs interface version, 32 bits
- value with major version number in upper 16 bits and
- minor version in lower 16 bits.
-=============== ======================================================
-
-* CREATE(1) and WRITE (5) command identifiers are unimplemented and
- return `SMC_UNK`.
-
--------------
-*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2017-2024, Arm Limited and Contributors. All rights reserved.*
.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest
diff --git a/docs/components/index.rst b/docs/components/index.rst
index 36ab6fa..18522f8 100644
--- a/docs/components/index.rst
+++ b/docs/components/index.rst
@@ -27,3 +27,4 @@
rmm-el3-comms-spec
granule-protection-tables-design
ven-el3-service
+ ven-el3-debugfs
diff --git a/docs/components/ven-el3-debugfs.rst b/docs/components/ven-el3-debugfs.rst
new file mode 100644
index 0000000..8629d70
--- /dev/null
+++ b/docs/components/ven-el3-debugfs.rst
@@ -0,0 +1,343 @@
+DebugFS interface
+=================
+
+The optional DebugFS interface is accessed through a Vendor specific EL3 service. Refer
+to the component documentation for details.
+
+String parameters are passed through a shared buffer using a specific union:
+
+.. code:: c
+
+ union debugfs_parms {
+ struct {
+ char fname[MAX_PATH_LEN];
+ } open;
+
+ struct mount {
+ char srv[MAX_PATH_LEN];
+ char where[MAX_PATH_LEN];
+ char spec[MAX_PATH_LEN];
+ } mount;
+
+ struct {
+ char path[MAX_PATH_LEN];
+ dir_t dir;
+ } stat;
+
+ struct {
+ char oldpath[MAX_PATH_LEN];
+ char newpath[MAX_PATH_LEN];
+ } bind;
+ };
+
+Format of the dir_t structure as such:
+
+.. code:: c
+
+ typedef struct {
+ char name[NAMELEN];
+ long length;
+ unsigned char mode;
+ unsigned char index;
+ unsigned char dev;
+ qid_t qid;
+ } dir_t;
+
+
+* Identifiers
+
+======================== =============================================
+SMC_OK 0
+SMC_UNK -1
+DEBUGFS_E_INVALID_PARAMS -2
+======================== =============================================
+
+======================== =============================================
+MOUNT 0
+CREATE 1
+OPEN 2
+CLOSE 3
+READ 4
+WRITE 5
+SEEK 6
+BIND 7
+STAT 8
+INIT 10
+VERSION 11
+======================== =============================================
+
+MOUNT
+~~~~~
+
+Description
+^^^^^^^^^^^
+This operation mounts a blob of data pointed to by path stored in `src`, at
+filesystem location pointed to by path stored in `where`, using driver pointed
+to by path in `spec`.
+
+Parameters
+^^^^^^^^^^
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``MOUNT``
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if mount operation failed
+=============== ==========================================================
+
+OPEN
+~~~~
+
+Description
+^^^^^^^^^^^
+This operation opens the file path pointed to by `fname`.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``OPEN``
+uint32_t mode
+======== ============================================================
+
+mode can be one of:
+
+.. code:: c
+
+ enum mode {
+ O_READ = 1 << 0,
+ O_WRITE = 1 << 1,
+ O_RDWR = 1 << 2,
+ O_BIND = 1 << 3,
+ O_DIR = 1 << 4,
+ O_STAT = 1 << 5
+ };
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if open operation failed
+
+uint32_t w1: file descriptor id on success.
+=============== ==========================================================
+
+CLOSE
+~~~~~
+
+Description
+^^^^^^^^^^^
+
+This operation closes a file described by a file descriptor obtained by a
+previous call to OPEN.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``CLOSE``
+uint32_t File descriptor id returned by OPEN
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if close operation failed
+=============== ==========================================================
+
+READ
+~~~~
+
+Description
+^^^^^^^^^^^
+
+This operation reads a number of bytes from a file descriptor obtained by
+a previous call to OPEN.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``READ``
+uint32_t File descriptor id returned by OPEN
+uint32_t Number of bytes to read
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+On success, the read data is retrieved from the shared buffer after the
+operation.
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if read operation failed
+
+uint32_t w1: number of bytes read on success.
+=============== ==========================================================
+
+SEEK
+~~~~
+
+Description
+^^^^^^^^^^^
+
+Move file pointer for file described by given `file descriptor` of given
+`offset` related to `whence`.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``SEEK``
+uint32_t File descriptor id returned by OPEN
+sint32_t offset in the file relative to whence
+uint32_t whence
+======== ============================================================
+
+whence can be one of:
+
+========= ============================================================
+KSEEK_SET 0
+KSEEK_CUR 1
+KSEEK_END 2
+========= ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if seek operation failed
+=============== ==========================================================
+
+BIND
+~~~~
+
+Description
+^^^^^^^^^^^
+
+Create a link from `oldpath` to `newpath`.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``BIND``
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if bind operation failed
+=============== ==========================================================
+
+STAT
+~~~~
+
+Description
+^^^^^^^^^^^
+
+Perform a stat operation on provided file `name` and returns the directory
+entry statistics into `dir`.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``STAT``
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ==========================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if stat operation failed
+=============== ==========================================================
+
+INIT
+~~~~
+
+Description
+^^^^^^^^^^^
+Initial call to setup the shared exchange buffer. Notice if successful once,
+subsequent calls fail after a first initialization. The caller maps the same
+page frame in its virtual space and uses this buffer to exchange string
+parameters with filesystem primitives.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``INIT``
+uint64_t Physical address of the shared buffer.
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ======================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == DEBUGFS_E_INVALID_PARAMS if already initialized,
+ or internal error occurred.
+=============== ======================================================
+
+VERSION
+~~~~~~~
+
+Description
+^^^^^^^^^^^
+Returns the debugfs interface version if implemented in TF-A.
+
+Parameters
+^^^^^^^^^^
+
+======== ============================================================
+uint32_t FunctionID (0x87000010 / 0xC7000010)
+uint32_t ``VERSION``
+======== ============================================================
+
+Return values
+^^^^^^^^^^^^^
+
+=============== ======================================================
+int32_t w0 == SMC_OK on success
+
+ w0 == SMC_UNK if interface is not implemented
+
+uint32_t w1: On success, debugfs interface version, 32 bits
+ value with major version number in upper 16 bits and
+ minor version in lower 16 bits.
+=============== ======================================================
+
+* CREATE(1) and WRITE (5) command identifiers are unimplemented and
+ return `SMC_UNK`.
+
+--------------
+
+*Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/components/ven-el3-service.rst b/docs/components/ven-el3-service.rst
index fe83845..fc9f13c 100644
--- a/docs/components/ven-el3-service.rst
+++ b/docs/components/ven-el3-service.rst
@@ -19,9 +19,26 @@
| 0xC7000000 - 0xC700FFFF | SMC64: Vendor Specific EL3 Monitor Service Calls |
+---------------------------+--------------------------------------------------+
+Vendor-specific EL3 monitor services are as follows:
+
++-----------------------------------+-----------------------+---------------------------------------------+
+| SMC Function Identifier | Service Type | FID's Usage |
++===================================+=======================+=============================================+
+| 0x87000010 - 0x8700001F (SMC32) | DebugFS Interface | | 0 - 11 are in use |
++-----------------------------------+ | | 12 - 15 are reserved for future expansion |
+| 0xC7000010 - 0xC700001F (SMC64) | | |
++-----------------------------------+-----------------------+---------------------------------------------+
+
Source definitions for vendor-specific EL3 Monitor Service Calls are located in
the ``ven_el3_svc.h`` header file.
+
+DebugFS interface
+-----------------
+
+The optional DebugFS interface is accessed through Vendor specific EL3 service. Refer
+to :ref:`DebugFS interface` documentation for further details and usage.
+
--------------
*Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.*