diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst index b51a94dc7..9bbedb0b7 100644 --- a/docs/components/arm-sip-service.rst +++ b/docs/components/arm-sip-service.rst @@ -17,7 +17,6 @@ The Arm SiP implementation offers the following services: - 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 @@ Instead, execution starts at the supplied entry point, with the CPU registers 0 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 36ab6fa1f..18522f88f 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -27,3 +27,4 @@ Components 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 000000000..8629d701d --- /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 fe8384553..fc9f13cbf 100644 --- a/docs/components/ven-el3-service.rst +++ b/docs/components/ven-el3-service.rst @@ -19,9 +19,26 @@ Levels below EL3. SMC calls for Vendor Specific EL3 Monitor Services: | 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.* diff --git a/include/lib/debugfs.h b/include/lib/debugfs.h index 8ed237ae2..941596278 100644 --- a/include/lib/debugfs.h +++ b/include/lib/debugfs.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019, Arm Limited. All rights reserved. + * Copyright (c) 2019-2024, Arm Limited. All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause */ @@ -61,12 +61,24 @@ int debugfs_smc_setup(void); /* Debugfs version returned through SMC interface */ #define DEBUGFS_VERSION (0x000000001U) -/* Function ID for accessing the debugfs interface */ -#define DEBUGFS_FID_VALUE (0x30U) +/* Function ID for accessing the debugfs interface from + * Vendor-Specific EL3 Range. + */ +#define DEBUGFS_FID_VALUE (0x10U) #define is_debugfs_fid(_fid) \ (((_fid) & FUNCID_NUM_MASK) == DEBUGFS_FID_VALUE) + +/* Function ID for accessing the debugfs interface from arm sip. + * This is now deprecated FID and will be removed after 2.12 release. + */ +#define DEBUGFS_FID_VALUE_DEPRECATED (0x30U) + +#define is_debugfs_fid_deprecated(_fid) \ + (((_fid) & FUNCID_NUM_MASK) == DEBUGFS_FID_VALUE_DEPRECATED) + + /* Error code for debugfs SMC interface failures */ #define DEBUGFS_E_INVALID_PARAMS (-2) #define DEBUGFS_E_DENIED (-3) diff --git a/include/plat/arm/common/arm_sip_svc.h b/include/plat/arm/common/arm_sip_svc.h index a6fd42bac..b3e41a757 100644 --- a/include/plat/arm/common/arm_sip_svc.h +++ b/include/plat/arm/common/arm_sip_svc.h @@ -22,6 +22,7 @@ /* Function ID for requesting state switch of lower EL */ #define ARM_SIP_SVC_EXE_STATE_SWITCH U(0x82000020) +/* Deprecated FID's Range and will be removed */ /* DEBUGFS_SMC_32 0x82000030U */ /* DEBUGFS_SMC_64 0xC2000030U */ @@ -32,8 +33,8 @@ */ /* ARM SiP Service Calls version numbers */ -#define ARM_SIP_SVC_VERSION_MAJOR U(0x0) -#define ARM_SIP_SVC_VERSION_MINOR U(0x2) +#define ARM_SIP_SVC_VERSION_MAJOR U(0x1) +#define ARM_SIP_SVC_VERSION_MINOR U(0x0) /* * Arm SiP SMC calls that are primarily used for testing purposes. diff --git a/include/services/ven_el3_svc.h b/include/services/ven_el3_svc.h index 505e4fd9b..5974a2b51 100644 --- a/include/services/ven_el3_svc.h +++ b/include/services/ven_el3_svc.h @@ -23,4 +23,7 @@ #define VEN_EL3_SVC_VERSION_MAJOR 1 #define VEN_EL3_SVC_VERSION_MINOR 0 +/* DEBUGFS_SMC_32 0x87000010U */ +/* DEBUGFS_SMC_64 0xC7000010U */ + #endif /* VEN_EL3_SVC_H */ diff --git a/plat/arm/common/arm_sip_svc.c b/plat/arm/common/arm_sip_svc.c index 09226f4b7..02a7a03f2 100644 --- a/plat/arm/common/arm_sip_svc.c +++ b/plat/arm/common/arm_sip_svc.c @@ -1,5 +1,5 @@ /* - * Copyright (c) 2016-2023, Arm Limited and Contributors. All rights reserved. + * Copyright (c) 2016-2024, Arm Limited and Contributors. All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause */ @@ -73,8 +73,9 @@ static uintptr_t arm_sip_handler(unsigned int smc_fid, #endif /* ENABLE_PMF */ #if USE_DEBUGFS - - if (is_debugfs_fid(smc_fid)) { + if (is_debugfs_fid_deprecated(smc_fid)) { + NOTICE("Debugfs Interface usage from arm-sip range is deprecated. \ + Please migrate smc call to vendor-specific el3 range.\n"); return debugfs_smc_handler(smc_fid, x1, x2, x3, x4, cookie, handle, flags); } diff --git a/services/el3/ven_el3_svc.c b/services/el3/ven_el3_svc.c index 327878ffd..de003ae46 100644 --- a/services/el3/ven_el3_svc.c +++ b/services/el3/ven_el3_svc.c @@ -8,6 +8,7 @@ #include #include +#include #include #include @@ -18,6 +19,12 @@ DEFINE_SVC_UUID2(ven_el3_svc_uid, static int ven_el3_svc_setup(void) { +#if USE_DEBUGFS + if (debugfs_smc_setup() != 0) { + return 1; + } +#endif /* USE_DEBUGFS */ + return 0; } @@ -33,6 +40,17 @@ static uintptr_t ven_el3_svc_handler(unsigned int smc_fid, void *handle, u_register_t flags) { +#if USE_DEBUGFS + /* + * Dispatch debugfs calls to debugfs SMC handler and return its + * return value. + */ + if (is_debugfs_fid(smc_fid)) { + return debugfs_smc_handler(smc_fid, x1, x2, x3, x4, cookie, + handle, flags); + } +#endif /* USE_DEBUGFS */ + switch (smc_fid) { case VEN_EL3_SVC_UID: /* Return UID to the caller */ @@ -42,7 +60,7 @@ static uintptr_t ven_el3_svc_handler(unsigned int smc_fid, SMC_RET2(handle, VEN_EL3_SVC_VERSION_MAJOR, VEN_EL3_SVC_VERSION_MINOR); break; default: - WARN("Unimplemented Vendor specific EL3 Service call: 0x%x\n", smc_fid); + WARN("Unimplemented vendor-specific EL3 Service call: 0x%x\n", smc_fid); SMC_RET1(handle, SMC_UNK); break; }