1*54fd6939SJiyong Park======== 2*54fd6939SJiyong ParkDebug FS 3*54fd6939SJiyong Park======== 4*54fd6939SJiyong Park 5*54fd6939SJiyong Park.. contents:: 6*54fd6939SJiyong Park 7*54fd6939SJiyong ParkOverview 8*54fd6939SJiyong Park-------- 9*54fd6939SJiyong Park 10*54fd6939SJiyong ParkThe *DebugFS* feature is primarily aimed at exposing firmware debug data to 11*54fd6939SJiyong Parkhigher SW layers such as a non-secure component. Such component can be the 12*54fd6939SJiyong ParkTFTF test payload or a Linux kernel module. 13*54fd6939SJiyong Park 14*54fd6939SJiyong ParkVirtual filesystem 15*54fd6939SJiyong Park------------------ 16*54fd6939SJiyong Park 17*54fd6939SJiyong ParkThe core functionality lies in a virtual file system based on a 9p file server 18*54fd6939SJiyong Parkinterface (`Notes on the Plan 9 Kernel Source`_ and 19*54fd6939SJiyong Park`Linux 9p remote filesystem protocol`_). 20*54fd6939SJiyong ParkThe implementation permits exposing virtual files, firmware drivers, and file blobs. 21*54fd6939SJiyong Park 22*54fd6939SJiyong ParkNamespace 23*54fd6939SJiyong Park~~~~~~~~~ 24*54fd6939SJiyong Park 25*54fd6939SJiyong ParkTwo namespaces are exposed: 26*54fd6939SJiyong Park 27*54fd6939SJiyong Park - # is used as root for drivers (e.g. #t0 is the first uart) 28*54fd6939SJiyong Park - / is used as root for virtual "files" (e.g. /fip, or /dev/uart) 29*54fd6939SJiyong Park 30*54fd6939SJiyong Park9p interface 31*54fd6939SJiyong Park~~~~~~~~~~~~ 32*54fd6939SJiyong Park 33*54fd6939SJiyong ParkThe associated primitives are: 34*54fd6939SJiyong Park 35*54fd6939SJiyong Park- Unix-like: 36*54fd6939SJiyong Park 37*54fd6939SJiyong Park - open(): create a file descriptor that acts as a handle to the file passed as 38*54fd6939SJiyong Park an argument. 39*54fd6939SJiyong Park - close(): close the file descriptor created by open(). 40*54fd6939SJiyong Park - read(): read from a file to a buffer. 41*54fd6939SJiyong Park - write(): write from a buffer to a file. 42*54fd6939SJiyong Park - seek(): set the file position indicator of a file descriptor either to a 43*54fd6939SJiyong Park relative or an absolute offset. 44*54fd6939SJiyong Park - stat(): get information about a file (type, mode, size, ...). 45*54fd6939SJiyong Park 46*54fd6939SJiyong Park.. code:: c 47*54fd6939SJiyong Park 48*54fd6939SJiyong Park int open(const char *name, int flags); 49*54fd6939SJiyong Park int close(int fd); 50*54fd6939SJiyong Park int read(int fd, void *buf, int n); 51*54fd6939SJiyong Park int write(int fd, void *buf, int n); 52*54fd6939SJiyong Park int seek(int fd, long off, int whence); 53*54fd6939SJiyong Park int stat(char *path, dir_t *dir); 54*54fd6939SJiyong Park 55*54fd6939SJiyong Park- Specific primitives : 56*54fd6939SJiyong Park 57*54fd6939SJiyong Park - mount(): create a link between a driver and spec. 58*54fd6939SJiyong Park - create(): create a file in a specific location. 59*54fd6939SJiyong Park - bind(): expose the content of a directory to another directory. 60*54fd6939SJiyong Park 61*54fd6939SJiyong Park.. code:: c 62*54fd6939SJiyong Park 63*54fd6939SJiyong Park int mount(char *srv, char *mnt, char *spec); 64*54fd6939SJiyong Park int create(const char *name, int flags); 65*54fd6939SJiyong Park int bind(char *path, char *where); 66*54fd6939SJiyong Park 67*54fd6939SJiyong ParkThis interface is embedded into the BL31 run-time payload when selected by build 68*54fd6939SJiyong Parkoptions. The interface multiplexes drivers or emulated "files": 69*54fd6939SJiyong Park 70*54fd6939SJiyong Park- Debug data can be partitioned into different virtual files e.g. expose PMF 71*54fd6939SJiyong Park measurements through a file, and internal firmware state counters through 72*54fd6939SJiyong Park another file. 73*54fd6939SJiyong Park- This permits direct access to a firmware driver, mainly for test purposes 74*54fd6939SJiyong Park (e.g. a hardware device that may not be accessible to non-privileged/ 75*54fd6939SJiyong Park non-secure layers, or for which no support exists in the NS side). 76*54fd6939SJiyong Park 77*54fd6939SJiyong ParkSMC interface 78*54fd6939SJiyong Park------------- 79*54fd6939SJiyong Park 80*54fd6939SJiyong ParkThe communication with the 9p layer in BL31 is made through an SMC conduit 81*54fd6939SJiyong Park(`SMC Calling Convention`_), using a specific SiP Function Id. An NS 82*54fd6939SJiyong Parkshared buffer is used to pass path string parameters, or e.g. to exchange 83*54fd6939SJiyong Parkdata on a read operation. Refer to :ref:`ARM SiP Services <arm sip services>` 84*54fd6939SJiyong Parkfor a description of the SMC interface. 85*54fd6939SJiyong Park 86*54fd6939SJiyong ParkSecurity considerations 87*54fd6939SJiyong Park----------------------- 88*54fd6939SJiyong Park 89*54fd6939SJiyong Park- Due to the nature of the exposed data, the feature is considered experimental 90*54fd6939SJiyong Park and importantly **shall only be used in debug builds**. 91*54fd6939SJiyong Park- Several primitive imply string manipulations and usage of string formats. 92*54fd6939SJiyong Park- Special care is taken with the shared buffer to avoid TOCTOU attacks. 93*54fd6939SJiyong Park 94*54fd6939SJiyong ParkLimitations 95*54fd6939SJiyong Park----------- 96*54fd6939SJiyong Park 97*54fd6939SJiyong Park- In order to setup the shared buffer, the component consuming the interface 98*54fd6939SJiyong Park needs to allocate a physical page frame and transmit its address. 99*54fd6939SJiyong Park- In order to map the shared buffer, BL31 requires enabling the dynamic xlat 100*54fd6939SJiyong Park table option. 101*54fd6939SJiyong Park- Data exchange is limited by the shared buffer length. A large read operation 102*54fd6939SJiyong Park might be split into multiple read operations of smaller chunks. 103*54fd6939SJiyong Park- On concurrent access, a spinlock is implemented in the BL31 service to protect 104*54fd6939SJiyong Park the internal work buffer, and re-entrancy into the filesystem layers. 105*54fd6939SJiyong Park- Notice, a physical device driver if exposed by the firmware may conflict with 106*54fd6939SJiyong Park the higher level OS if the latter implements its own driver for the same 107*54fd6939SJiyong Park physical device. 108*54fd6939SJiyong Park 109*54fd6939SJiyong ParkApplications 110*54fd6939SJiyong Park------------ 111*54fd6939SJiyong Park 112*54fd6939SJiyong ParkThe SMC interface is accessible from an NS environment, that is: 113*54fd6939SJiyong Park 114*54fd6939SJiyong Park- a test payload, bootloader or hypervisor running at NS-EL2 115*54fd6939SJiyong Park- a Linux kernel driver running at NS-EL1 116*54fd6939SJiyong Park- a Linux userspace application through the kernel driver 117*54fd6939SJiyong Park 118*54fd6939SJiyong Park-------------- 119*54fd6939SJiyong Park 120*54fd6939SJiyong Park*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* 121*54fd6939SJiyong Park 122*54fd6939SJiyong Park.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest 123*54fd6939SJiyong Park.. _Notes on the Plan 9 Kernel Source: http://lsub.org/who/nemo/9.pdf 124*54fd6939SJiyong Park.. _Linux 9p remote filesystem protocol: https://www.kernel.org/doc/Documentation/filesystems/9p.txt 125*54fd6939SJiyong Park.. _ARM SiP Services: arm-sip-service.rst 126