Gitiles
Code Review Sign In
git01.mediatek.com / filogic / atf / 4fb9d8e8d3cbc7d5a1925aa2498dc2bf882bcf90 / . / docs / components / ven-el3-debugfs.rst
blob: 8629d701d70bf604c1442ace4afb7266db6f3bec [file] [log] [blame]
Govindraj Raja79cd7a02024-03-07 15:24:19 -0600[diff] [blame]1DebugFS interface
2=================
3
4The optional DebugFS interface is accessed through a Vendor specific EL3 service. Refer
5to the component documentation for details.
6
7String parameters are passed through a shared buffer using a specific union:
8
9.. code:: c
10
11 union debugfs_parms {
12 struct {
13 char fname[MAX_PATH_LEN];
14 } open;
15
16 struct mount {
17 char srv[MAX_PATH_LEN];
18 char where[MAX_PATH_LEN];
19 char spec[MAX_PATH_LEN];
20 } mount;
21
22 struct {
23 char path[MAX_PATH_LEN];
24 dir_t dir;
25 } stat;
26
27 struct {
28 char oldpath[MAX_PATH_LEN];
29 char newpath[MAX_PATH_LEN];
30 } bind;
31 };
32
33Format of the dir_t structure as such:
34
35.. code:: c
36
37 typedef struct {
38 char name[NAMELEN];
39 long length;
40 unsigned char mode;
41 unsigned char index;
42 unsigned char dev;
43 qid_t qid;
44 } dir_t;
45
46
47* Identifiers
48
49======================== =============================================
50SMC_OK 0
51SMC_UNK -1
52DEBUGFS_E_INVALID_PARAMS -2
53======================== =============================================
54
55======================== =============================================
56MOUNT 0
57CREATE 1
58OPEN 2
59CLOSE 3
60READ 4
61WRITE 5
62SEEK 6
63BIND 7
64STAT 8
65INIT 10
66VERSION 11
67======================== =============================================
68
69MOUNT
70~~~~~
71
72Description
73^^^^^^^^^^^
74This operation mounts a blob of data pointed to by path stored in `src`, at
75filesystem location pointed to by path stored in `where`, using driver pointed
76to by path in `spec`.
77
78Parameters
79^^^^^^^^^^
80======== ============================================================
81uint32_t FunctionID (0x87000010 / 0xC7000010)
82uint32_t ``MOUNT``
83======== ============================================================
84
85Return values
86^^^^^^^^^^^^^
87
88=============== ==========================================================
89int32_t w0 == SMC_OK on success
90
91 w0 == DEBUGFS_E_INVALID_PARAMS if mount operation failed
92=============== ==========================================================
93
94OPEN
95~~~~
96
97Description
98^^^^^^^^^^^
99This operation opens the file path pointed to by `fname`.
100
101Parameters
102^^^^^^^^^^
103
104======== ============================================================
105uint32_t FunctionID (0x87000010 / 0xC7000010)
106uint32_t ``OPEN``
107uint32_t mode
108======== ============================================================
109
110mode can be one of:
111
112.. code:: c
113
114 enum mode {
115 O_READ = 1 << 0,
116 O_WRITE = 1 << 1,
117 O_RDWR = 1 << 2,
118 O_BIND = 1 << 3,
119 O_DIR = 1 << 4,
120 O_STAT = 1 << 5
121 };
122
123Return values
124^^^^^^^^^^^^^
125
126=============== ==========================================================
127int32_t w0 == SMC_OK on success
128
129 w0 == DEBUGFS_E_INVALID_PARAMS if open operation failed
130
131uint32_t w1: file descriptor id on success.
132=============== ==========================================================
133
134CLOSE
135~~~~~
136
137Description
138^^^^^^^^^^^
139
140This operation closes a file described by a file descriptor obtained by a
141previous call to OPEN.
142
143Parameters
144^^^^^^^^^^
145
146======== ============================================================
147uint32_t FunctionID (0x87000010 / 0xC7000010)
148uint32_t ``CLOSE``
149uint32_t File descriptor id returned by OPEN
150======== ============================================================
151
152Return values
153^^^^^^^^^^^^^
154=============== ==========================================================
155int32_t w0 == SMC_OK on success
156
157 w0 == DEBUGFS_E_INVALID_PARAMS if close operation failed
158=============== ==========================================================
159
160READ
161~~~~
162
163Description
164^^^^^^^^^^^
165
166This operation reads a number of bytes from a file descriptor obtained by
167a previous call to OPEN.
168
169Parameters
170^^^^^^^^^^
171
172======== ============================================================
173uint32_t FunctionID (0x87000010 / 0xC7000010)
174uint32_t ``READ``
175uint32_t File descriptor id returned by OPEN
176uint32_t Number of bytes to read
177======== ============================================================
178
179Return values
180^^^^^^^^^^^^^
181
182On success, the read data is retrieved from the shared buffer after the
183operation.
184
185=============== ==========================================================
186int32_t w0 == SMC_OK on success
187
188 w0 == DEBUGFS_E_INVALID_PARAMS if read operation failed
189
190uint32_t w1: number of bytes read on success.
191=============== ==========================================================
192
193SEEK
194~~~~
195
196Description
197^^^^^^^^^^^
198
199Move file pointer for file described by given `file descriptor` of given
200`offset` related to `whence`.
201
202Parameters
203^^^^^^^^^^
204
205======== ============================================================
206uint32_t FunctionID (0x87000010 / 0xC7000010)
207uint32_t ``SEEK``
208uint32_t File descriptor id returned by OPEN
209sint32_t offset in the file relative to whence
210uint32_t whence
211======== ============================================================
212
213whence can be one of:
214
215========= ============================================================
216KSEEK_SET 0
217KSEEK_CUR 1
218KSEEK_END 2
219========= ============================================================
220
221Return values
222^^^^^^^^^^^^^
223
224=============== ==========================================================
225int32_t w0 == SMC_OK on success
226
227 w0 == DEBUGFS_E_INVALID_PARAMS if seek operation failed
228=============== ==========================================================
229
230BIND
231~~~~
232
233Description
234^^^^^^^^^^^
235
236Create a link from `oldpath` to `newpath`.
237
238Parameters
239^^^^^^^^^^
240
241======== ============================================================
242uint32_t FunctionID (0x87000010 / 0xC7000010)
243uint32_t ``BIND``
244======== ============================================================
245
246Return values
247^^^^^^^^^^^^^
248
249=============== ==========================================================
250int32_t w0 == SMC_OK on success
251
252 w0 == DEBUGFS_E_INVALID_PARAMS if bind operation failed
253=============== ==========================================================
254
255STAT
256~~~~
257
258Description
259^^^^^^^^^^^
260
261Perform a stat operation on provided file `name` and returns the directory
262entry statistics into `dir`.
263
264Parameters
265^^^^^^^^^^
266
267======== ============================================================
268uint32_t FunctionID (0x87000010 / 0xC7000010)
269uint32_t ``STAT``
270======== ============================================================
271
272Return values
273^^^^^^^^^^^^^
274
275=============== ==========================================================
276int32_t w0 == SMC_OK on success
277
278 w0 == DEBUGFS_E_INVALID_PARAMS if stat operation failed
279=============== ==========================================================
280
281INIT
282~~~~
283
284Description
285^^^^^^^^^^^
286Initial call to setup the shared exchange buffer. Notice if successful once,
287subsequent calls fail after a first initialization. The caller maps the same
288page frame in its virtual space and uses this buffer to exchange string
289parameters with filesystem primitives.
290
291Parameters
292^^^^^^^^^^
293
294======== ============================================================
295uint32_t FunctionID (0x87000010 / 0xC7000010)
296uint32_t ``INIT``
297uint64_t Physical address of the shared buffer.
298======== ============================================================
299
300Return values
301^^^^^^^^^^^^^
302
303=============== ======================================================
304int32_t w0 == SMC_OK on success
305
306 w0 == DEBUGFS_E_INVALID_PARAMS if already initialized,
307 or internal error occurred.
308=============== ======================================================
309
310VERSION
311~~~~~~~
312
313Description
314^^^^^^^^^^^
315Returns the debugfs interface version if implemented in TF-A.
316
317Parameters
318^^^^^^^^^^
319
320======== ============================================================
321uint32_t FunctionID (0x87000010 / 0xC7000010)
322uint32_t ``VERSION``
323======== ============================================================
324
325Return values
326^^^^^^^^^^^^^
327
328=============== ======================================================
329int32_t w0 == SMC_OK on success
330
331 w0 == SMC_UNK if interface is not implemented
332
333uint32_t w1: On success, debugfs interface version, 32 bits
334 value with major version number in upper 16 bits and
335 minor version in lower 16 bits.
336=============== ======================================================
337
338* CREATE(1) and WRITE (5) command identifiers are unimplemented and
339 return `SMC_UNK`.
340
341--------------
342
343*Copyright (c) 2024, Arm Limited and Contributors. All rights reserved.*