1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 /** 16 * @defgroup seq_file Seq_file 17 * @ingroup linux 18 */ 19 20 #ifndef _LINUX_SEQ_FILE_H 21 #define _LINUX_SEQ_FILE_H 22 23 #include "sys/types.h" 24 #include "pthread.h" 25 #include "linux/types.h" 26 #include "linux/list.h" 27 #include "linux/kernel.h" 28 #ifdef LOSCFG_FS_VFS 29 #include "fs/fs.h" 30 #ifdef LOSCFG_FS_PROC 31 #include "proc_fs.h" 32 #endif 33 #endif 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif /* __cplusplus */ 38 39 typedef char seq_char; 40 typedef size_t seq_size_t; 41 typedef loff_t seq_loff_t; 42 typedef int seq_int; 43 typedef void seq_void; 44 45 struct seq_file { 46 seq_char *buf; /**< Data buffer for sequential file. */ 47 seq_size_t size; /**< Size of the buf. */ 48 seq_size_t from; /**< The start offset of the data that is not copied in the buf. */ 49 seq_size_t count; /**< Bytes of data that can be copied. */ 50 seq_loff_t index; /**< Index of the operation provided to the start and next functions. */ 51 seq_loff_t read_pos; /**< Size of the data that has been copied. */ 52 unsigned long long version; /**< Version of the sequential file. */ 53 pthread_mutex_t lock; /**< Mutex lock for this seq_file operation. */ 54 const struct seq_operations *op; /**< Point to a function that manipulates the underlying data. */ 55 seq_int poll_event; /**< Not used. */ 56 seq_void *private; /**< Private data of sequential file. */ 57 }; 58 59 typedef struct seq_operations { 60 void *(*start)(struct seq_file *, loff_t *); /**< Start read data. */ 61 void (*stop)(struct seq_file *, void *); /**< Stop read data. */ 62 void *(*next)(struct seq_file *, void *, loff_t *); /**< Gets the next data to be processed. */ 63 int (*show)(struct seq_file *, void *); /**< Print data to temporary buffer. */ 64 } seq_operations_t; 65 66 struct proc_file; 67 68 /** 69 * @ingroup seq_file 70 * @brief initialize sequential file. 71 * 72 * @par Description: 73 * seq_open sets procfilep, associating it with a sequence described by op. 74 * @attention 75 * <ul> 76 * <li> The input parameter procfilep and op must point to valid memory, 77 * or it will return errno -1.</li> 78 * <li> It is recommended that user call the single_open interface to replace this interface.</li> 79 * </ul> 80 * 81 * @param procfilep [IN] the file to initialize. 82 * @param op [IN] method table describing the sequence. 83 * 84 * @retval #-1 initialize sequential file fail. 85 * @retval #0 initialize sequential file success. 86 * @par Dependency: 87 * <ul><li>seq_file.h: the header file that contains the API declaration.</li></ul> 88 * @see seq_realse 89 */ 90 int seq_open(struct proc_file *procfilep, const struct seq_operations *op); 91 92 /** 93 * @ingroup seq_file 94 * @brief read method for sequential files. 95 * 96 * @par Description: 97 * This API is used to read method for sequential files, and wirte the relevant 98 * kernel real-time data into the seq files, then presented to the user. 99 * @attention 100 * <ul> 101 * <li> The input parameter procfilep and buf and ppos must point to valid memory, 102 * and the value of ppos point to should >=0, or it will lead read file fail.</li> 103 * <li> when the user call this interface, should call the single_open first.</li> 104 * </ul> 105 * 106 * @param procfilep [IN] the proc file struct to read from. 107 * @param buf [IN] the buffer to read to. 108 * @param readsize [IN] the maximum number of bytes to read. 109 * @param ppos [IN] the current position in the file to read from. 110 * 111 * @retval #-1 read file fail. 112 * @retval ssize_t the real read size copy into the buf. 113 * @par Dependency: 114 * <ul><li>seq_file.h: the header file that contains the API declaration.</li></ul> 115 * @see None. 116 */ 117 ssize_t seq_read(struct proc_file *procfilep, char *buf, size_t readsize, loff_t *ppos); 118 119 /** 120 * @ingroup seq_file 121 * @brief llseek method for sequential files. 122 * 123 * @par Description: 124 * This API is used to llseek method for sequential files. 125 * @attention 126 * <ul> 127 * <li>The input parameter procfilep must point to valid memory.</li> 128 * <li>origin should be SEEK_SET(seek from start of file) or SEEK_CUR(seek from 129 * current position of file), seek from the end of file are not supported.</li> 130 * </ul> 131 * 132 * @param procfilep [IN] the proc file struct to seek. 133 * @param offset [IN] the relative position in the file to seek. 134 * @param origin [IN] SEEK_SET means the offset is relative to the start of the file, 135 * SEEK_CUR means the offset is relative to the current position of the file. 136 * 137 * @retval loff_t the absolute offset. 138 * @retval #-1 operation not permitted. 139 * @retval #-EINVAL invalid argument. 140 * @par Dependency: 141 * <ul><li>seq_file.h: the header file that contains the API declaration.</li></ul> 142 * @see None. 143 */ 144 loff_t seq_lseek(struct proc_file *procfilep, loff_t offset, int origin); 145 146 /** 147 * @ingroup seq_file 148 * @brief free the structures associated with sequential file. 149 * 150 * @par Description: 151 * This API is used to free the structures associated with sequential file. 152 * @attention 153 * <ul> 154 * <li> The input parameter procfilep must point to valid memory.</li> 155 * <li> It is recommended that user call the single_release interface to replace 156 * this interface.</li> 157 * <li> if use this interface, it must call the seq_open first.</li> 158 * </ul> 159 * 160 * @param inodep [IN] its inode (not used). 161 * @param procfilep [IN] pointer to proc file which is opened. 162 * 163 * @retval #-1 release file failed. 164 * @retval #0 release file success. 165 * @par Dependency: 166 * <ul><li>seq_file.h: the header file that contains the API declaration.</li></ul> 167 * @see seq_open 168 */ 169 int seq_release(struct inode *inodep, struct proc_file *procfilep); 170 171 /** 172 * @ingroup seq_file 173 * @brief print a formatted string and variable data to the seq_file output buffer. 174 * 175 * @par Description: 176 * This API is used to write the kernel data into the seq file with a certain format. 177 * 178 * @attention 179 * <ul> 180 * <li>The input parameter seqfilep must point to valid memory.</li> 181 * <li>The size of seq file must less than 1M Bytes.</li> 182 * </ul> 183 * 184 * @param seqfilep [IN] pointer to the seq file. 185 * @param f [IN] format control string. 186 * 187 * @retval #0 seq printf success. 188 * @retval #-1 seq printf failed. 189 * @par Dependency: 190 * <ul><li>Seq_file.h: the header file that contains the API declaration.</li></ul> 191 * @see None. 192 */ 193 int seq_printf(struct seq_file *seqfilep, const char *f, ...); 194 195 /** 196 * @ingroup seq_file 197 * @brief open the seq stream. 198 * 199 * @par Description: 200 * This API is used to open the seq stream. 201 * 202 * @attention 203 * <ul> 204 * <li>Please make sure all the input parameters are valid.</li> 205 * </ul> 206 * 207 * @param procfilep [IN] pointer to the procfile. 208 * @param show [IN] pointer to the "show" function for construct seq file. 209 * @param data [IN] pointer to the data that is to be written. 210 * 211 * @retval #0 open the seq stream succeed. 212 * @retval #-1 open seq failed. 213 * @par Dependency: 214 * <ul><li>Seq_file.h: the header file that contains the API declaration.</li></ul> 215 * @see single_release 216 */ 217 int single_open(struct proc_file *procfilep, int (*show)(struct seq_file *, void *), void *data); 218 219 /** 220 * @ingroup seq_file 221 * @brief release the memory malloced by single_open. 222 * 223 * @par Description: 224 * This API is used to release the memory malloced by single_open. 225 * 226 * @attention 227 * <ul> 228 * <li>Please make sure all the input parameters are valid.</li> 229 * <li>if use this interface, it must call the single_open at first.</li> 230 * </ul> 231 * 232 * @param inodep [IN] pointer to struct inode. 233 * @param procfilep [IN] pointer to struct proc_file. 234 * 235 * @retval #0 success to release seq file. 236 * @retval #-1 fail to release seq file. 237 * @par Dependency: 238 * <ul><li>Seq_file.h: the header file that contains the API declaration.</li></ul> 239 * @see single_open 240 */ 241 int single_release(struct inode *inodep, struct proc_file *procfilep); 242 243 #ifdef __cplusplus 244 } 245 #endif /* __cplusplus */ 246 247 #endif /* _LINUX_SEQ_FILE_H */ 248