1 /*
2  * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 
8 /**
9  * Archive to parse cpio data in the newc and crc formats. Generate a cpio archive like that by e.g.
10  * find . | cpio -o -H newc > archive.cpio
11  */
12 
13 #pragma once
14 
15 #include <stdio.h>
16 #include <stdint.h>
17 #include <stdbool.h>
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 #define CPIO_MODE_FILETYPE_MASK     0xF000
24 #define CPIO_MODE_FILETYPE_SOCKET   0xC000
25 #define CPIO_MODE_FILETYPE_SYMLINK  0xA000
26 #define CPIO_MODE_FILETYPE_REGULAR  0x8000
27 #define CPIO_MODE_FILETYPE_BLOCKDEV 0x6000
28 #define CPIO_MODE_FILETYPE_DIR      0x4000
29 #define CPIO_MODE_FILETYPE_CHARDEV  0x2000
30 #define CPIO_MODE_FILETYPE_FIFO     0x1000
31 #define CPIO_MODE_SUID              0x0800
32 #define CPIO_MODE_SGID              0x0400
33 #define CPIO_MODE_STICKY            0x0200
34 
35 typedef struct {
36     size_t filesize;
37     char *name;
38     uint32_t mode;
39     uint32_t check;
40 } cpio_file_t;
41 
42 typedef enum {
43     CPIO_RET_MORE = 0,
44     CPIO_RET_DONE,
45     CPIO_RET_ERR
46 } cpio_ret_t;
47 
48 typedef struct cpio_handle_data_t cpio_handle_data_t;
49 typedef cpio_handle_data_t *cpio_handle_t;
50 
51 typedef enum {
52     CPIO_RSN_FILE_ALL = 0,
53     CPIO_RSN_FILE_INITIAL,
54     CPIO_RSN_FILE_MORE,
55     CPIO_RSN_FILE_END
56 } cpio_callback_reason_t;
57 
58 
59 /**
60  * Callback for cpio file data.
61  *
62  * This callback will be called by the library to indicate data for a file is available.
63  *
64  * For files in the cpio archive that fit entirely in the internal buffer, or when no internal
65  * buffer is available, are entirely contained in the buffer fed to cpio_feed(), this callback
66  * is only called once, with reason=CPIO_RNS_FILE_ALL. fileinfo will contain the information
67  * for that specific file (name, size, ...), buff_offset will be 0, buff_len is the file
68  * size and buff contains all the information for the file.
69  *
70  * For files that do not fit in the buffer, this callback will be called multiple times.
71  * The initial time with reason=CPIO_RSN_FILE_INITIAL, when more data is available with
72  * CPIO_RSN_FILE_MORE and finally with CPIO_RSN_FILE_END. For these calls, fileinfo
73  * will again contain file information. buff will be the information contained in the
74  * file at offset buff_offset, and the length of this buffer will be in buff_len.
75  *
76  * The library guarantees to feed all file data to the callback consequitively, so
77  * within the same file, the buff_offset from a call will always be (buff_offset+buff_len)
78  * from the call before that. If cpio_start is
79  *
80  * The library also guarantees every file in the cpio archive will either generate a single
81  * callback call with CPIO_RSN_ALL, or multiple with in sequence CPIO_RSN_FILE_INITIAL, 0 or
82  * more CPIO_RSN_FILE_MORE and finally a CPIO_RSN_FILE_END.
83  *
84  * When a non-zero buffer size is passed to cpio_start, the library guarantees that all callback
85  * calls with a reason of CPIO_RSN_FILE_INITIAL and CPIO_RSN_FILE_MORE will have a buffer
86  * filled with exactly this amount of bytes.
87  *
88  */
89 typedef void (*cpio_callback_t)(cpio_callback_reason_t reason, cpio_file_t *fileinfo, size_t buff_offset, size_t buff_len, char *buff, void *arg);
90 
91 
92 /**
93  * @brief      Initialize a cpio handle.
94  *
95  * Call this to start parsing a cpio archive. You can set the callback that handles the
96  * files/data here.
97  *
98  * @param  callback The callback that will handle the data of the files inside the cpio archive
99  *
100  * @param  cbarg User-supplied argument. The callback will be called with this as an argument.
101  *
102  * @param  buflen Length of internal buffer used.
103  *                If this is zero, the callback will be called with data that lives in the data buffer
104  *                supplied to the cpio library by whomever called cpio_feed(). Because this library has
105  *                no power over that buffer, the callback can be passed as little as 1 and as many as
106  *                INT_MAX bytes at a time.
107  *                If this is non-zero, the library will allocate an internal buffer of this size. All
108  *                cpio_feed()-calls will be rebuffered, and the callback is guaranteed to only be called
109  *                with this many bytes in the buffer, given there's enough data in the file to fill it.
110  *
111  * @param memchunk Chunk of memory to allocate everything (handle, I/O buffer, filename buffer) in. Minimum size
112  *                 (estimate) is 160+buflen+sizeof(largest filename/path).
113  * @param memchunklen Size of the mem chunk
114  *
115  * @return
116  *     - Success: A pointer to a cpio handle
117  *     - Error: NULL
118  *
119  */
120 cpio_handle_t cpio_start(cpio_callback_t callback, void *cbarg, size_t buflen, void *memchunk, int memchunklen);
121 
122 /**
123  * @brief      Feed data from a cpio archive into the library
124  *
125  * This routine is used to feed consecutive data of the cpio archive into the library. While processing,
126  * the library can call the callback function one or more times if needed.
127  *
128  * @param  cpio Handle obtained by calling cpio_start()
129  *
130  * @param  buffer Pointer to buffer containing cpio archive data
131  *
132  * @param  len Length of the buffer, in bytes
133  *
134  * @return
135  *     - CPIO_RET_MORE: CPIO archive isn't done yet, please feed more data.
136  *     - CPIO_RET_DONE: CPUI archive is finished.
137  *     - CPIO_RET_ERR: Invalid CPIO archive data; decoding aborted.
138  *
139  */
140 cpio_ret_t cpio_feed(cpio_handle_t cpio, char *buffer, int len);
141 
142 /**
143  * @brief      Indicate there is no more cpio data to be fed into the archive
144  *
145  * This call is to be called when the source data is exhausted. Normally, the library can find the end of the
146  * cpio archive by looking for the end marker,
147  *
148  * @param  timer_conf Pointer of LEDC timer configure struct
149  *
150  *
151  * @return
152  *     - CPIO_RET_DONE on success
153  *     - CPIO_RET_ERR when cpio archive is invalid
154  *
155  */
156 cpio_ret_t cpio_done(cpio_handle_t cpio);
157 
158 
159 /**
160  * @brief      Free the memory allocated for a cpio handle.
161  *
162  * @param  cpio Handle obtained by calling cpio_start()
163  *
164  * @return
165  *     - CPIO_RET_DONE on success
166  *
167  */
168 cpio_ret_t cpio_destroy(cpio_handle_t cpio);
169 
170 #ifdef __cplusplus
171 }
172 #endif
173