1 /* SPDX-License-Identifier: BSD-2-Clause */
2 /*
3  * Copyright (c) 2019, Linaro Limited
4  */
5 
6 #ifndef __MM_FILE_H
7 #define __MM_FILE_H
8 
9 #include <tee_api_types.h>
10 #include <types_ext.h>
11 #include <utee_defines.h>
12 
13 /* This is supposed to be large enough to hold any hash or tag used */
14 #define FILE_TAG_SIZE	TEE_SHA256_HASH_SIZE
15 
16 /*
17  * struct file_slice - one slice of a file
18  * @fobj:	 Fobj holding the data of this slice
19  * @page_offset: Offset in pages into the file where the @fobj is
20  *		 located.
21  */
22 struct file_slice {
23 	struct fobj *fobj;
24 	unsigned int page_offset;
25 };
26 
27 struct file;
28 
29 /*
30  * file_lock() - Lock the file
31  * @f:		File pointer
32  *
33  * Waits until the file can be locked and with the file put in locked state.
34  */
35 void file_lock(struct file *f);
36 
37 /*
38  * file_lock() - Try to lock the file without blocking
39  * @f:		File pointer
40  *
41  * Returns false if file cannot be locked without blocking.
42  * Returns true if the file has been put in locked state.
43  */
44 bool file_trylock(struct file *f);
45 
46 /*
47  * file_unlock() - Unlock the file
48  * @f:		File pointer
49  *
50  * File must be in locked state. Releases the previous lock and returns.
51  */
52 void file_unlock(struct file *f);
53 
54 /*
55  * file_add_slice() - Add a slice to a file
56  * @f:		 File pointer
57  * @fobj:	 Fobj holding the data of this slice
58  * @page_offset: Offset in pages into the file (@f) where the @fobj is
59  *		 located.
60  *
61  * File must be in locked state.
62  *
63  * Returns TEE_SUCCESS on success or a TEE_ERROR_* code on failure.
64  */
65 TEE_Result file_add_slice(struct file *f, struct fobj *fobj,
66 			  unsigned int page_offset);
67 
68 /*
69  * file_get() - Increase file reference counter
70  * @f:		File pointer
71  *
72  * Returns @f, if @f isn't NULL its reference counter is first increased.
73  */
74 struct file *file_get(struct file *f);
75 
76 /*
77  * file_get_by_tag() - Finds a file based on tag and increase reference counter
78  * @tag:	Tag of the file
79  * @taglen:	Length of @tag
80  *
81  * If a file doesn't exist it's created with the supplied tag.
82  *
83  * Returns a file with an increased reference counter, or NULL on failure.
84  */
85 struct file *file_get_by_tag(const uint8_t *tag, unsigned int taglen);
86 
87 /*
88  * file_put() - Decrease reference counter of file
89  * @f:		File pointer
90  *
91  * If reference counter reaches 0, matching the numbers of file_new() +
92  * file_get() + file_get_by_tag(), the file is removed with reference
93  * counters for all contained fobjs decreased.
94  */
95 void file_put(struct file *f);
96 
97 /*
98  * file_find_slice() - Find a slice covering the @page_offset
99  * @f:		 File pointer
100  * @page_offset: Offset that must be covered
101  *
102  * File must be in locked state.
103  *
104  * If a matching file slice is found it is returned, else NULL is returned.
105  */
106 struct file_slice *file_find_slice(struct file *f, unsigned int page_offset);
107 
108 #endif /*__MM_FILE_H*/
109 
110