esp-idf/components/esp_rom/include/esp32s3/rom/usb/cpio.h

// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


/**
 * Archive to parse cpio data in the newc and crc formats. Generate a cpio archive like that by e.g.
 * find . | cpio -o -H newc > archive.cpio
 */

#pragma once

#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

#define CPIO_MODE_FILETYPE_MASK     0xF000
#define CPIO_MODE_FILETYPE_SOCKET   0xC000
#define CPIO_MODE_FILETYPE_SYMLINK  0xA000
#define CPIO_MODE_FILETYPE_REGULAR  0x8000
#define CPIO_MODE_FILETYPE_BLOCKDEV 0x6000
#define CPIO_MODE_FILETYPE_DIR      0x4000
#define CPIO_MODE_FILETYPE_CHARDEV  0x2000
#define CPIO_MODE_FILETYPE_FIFO     0x1000
#define CPIO_MODE_SUID              0x0800
#define CPIO_MODE_SGID              0x0400
#define CPIO_MODE_STICKY            0x0200

typedef struct {
    size_t filesize;
    char *name;
    uint32_t mode;
    uint32_t check;
} cpio_file_t;

typedef enum {
    CPIO_RET_MORE = 0,
    CPIO_RET_DONE,
    CPIO_RET_ERR
} cpio_ret_t;

typedef struct cpio_handle_data_t cpio_handle_data_t;
typedef cpio_handle_data_t *cpio_handle_t;

typedef enum {
    CPIO_RSN_FILE_ALL = 0,
    CPIO_RSN_FILE_INITIAL,
    CPIO_RSN_FILE_MORE,
    CPIO_RSN_FILE_END
} cpio_callback_reason_t;


/**
 * Callback for cpio file data.
 *
 * This callback will be called by the library to indicate data for a file is available.
 *
 * For files in the cpio archive that fit entirely in the internal buffer, or when no internal
 * buffer is available, are entirely contained in the buffer fed to cpio_feed(), this callback
 * is only called once, with reason=CPIO_RNS_FILE_ALL. fileinfo will contain the information
 * for that specific file (name, size, ...), buff_offset will be 0, buff_len is the file
 * size and buff contains all the information for the file.
 *
 * For files that do not fit in the buffer, this callback will be called multiple times.
 * The initial time with reason=CPIO_RSN_FILE_INITIAL, when more data is available with
 * CPIO_RSN_FILE_MORE and finally with CPIO_RSN_FILE_END. For these calls, fileinfo
 * will again contain file information. buff will be the information contained in the
 * file at offset buff_offset, and the lenght of this buffer will be in buff_len.
 *
 * The library guarantees to feed all file data to the callback consequitively, so
 * within the same file, the buff_offset from a call will always be (buff_offset+buff_len)
 * from the call before that. If cpio_start is
 *
 * The library also guarantees every file in the cpio archive will either generate a single
 * callback call with CPIO_RSN_ALL, or multiple with in sequence CPIO_RSN_FILE_INITIAL, 0 or
 * more CPIO_RSN_FILE_MORE and finally a CPIO_RSN_FILE_END.
 *
 * When a non-zero buffer size is passed to cpio_start, the library guarantees that all callback
 * calls with a reason of CPIO_RSN_FILE_INITIAL and CPIO_RSN_FILE_MORE will have a buffer
 * filled with exactly this amount of bytes.
 *
 */
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);


/**
 * @brief      Initialize a cpio handle.
 *
 * Call this to start parsing a cpio archive. You can set the callback that handles the
 * files/data here.
 *
 * @param  callback The callback that will handle the data of the files inside the cpio archive
 *
 * @param  cbarg User-supplied argument. The callback will be called with this as an argument.
 *
 * @param  buflen Length of internal buffer used.
 *                If this is zero, the callback will be called with data that lives in the data buffer
 *                supplied to the cpio library by whomever called cpio_feed(). Because this library has
 *                no power over that buffer, the callback can be passed as little as 1 and as many as
 *                INT_MAX bytes at a time.
 *                If this is non-zero, the library will allocate an internal buffer of this size. All
 *                cpio_feed()-calls will be rebuffered, and the callback is guaranteed to only be called
 *                with this many bytes in the buffer, given there's enough data in the file to fill it.
 *
 * @param memchunk Chunk of memory to allocate everything (handle, I/O buffer, filename buffer) in. Minimum size
 *                 (estimate) is 160+buflen+sizeof(largest filename/path).
 * @param memchunklen Size of the mem chunk
 *
 * @return
 *     - Success: A pointer to a cpio handle
 *     - Error: NULL
 *
 */
cpio_handle_t cpio_start(cpio_callback_t callback, void *cbarg, size_t buflen, void *memchunk, int memchunklen);

/**
 * @brief      Feed data from a cpio archive into the library
 *
 * This routine is used to feed consecutive data of the cpio archive into the library. While processing,
 * the library can call the callback function one or more times if needed.
 *
 * @param  cpio Handle obtained by calling cpio_start()
 *
 * @param  buffer Pointer to buffer containing cpio archive data
 *
 * @param  len Length of the buffer, in bytes
 *
 * @return
 *     - CPIO_RET_MORE: CPIO archive isn't done yet, please feed more data.
 *     - CPIO_RET_DONE: CPUI archive is finished.
 *     - CPIO_RET_ERR: Invalid CPIO archive data; decoding aborted.
 *
 */
cpio_ret_t cpio_feed(cpio_handle_t cpio, char *buffer, int len);

/**
 * @brief      Indicate there is no more cpio data to be fed into the archive
 *
 * This call is to be called when the source data is exhausted. Normally, the library can find the end of the
 * cpio archive by looking for the end marker,
 *
 * @param  timer_conf Pointer of LEDC timer configure struct
 *
 *
 * @return
 *     - CPIO_RET_DONE on success
 *     - CPIO_RET_ERR when cpio archive is invalid
 *
 */
cpio_ret_t cpio_done(cpio_handle_t cpio);


/**
 * @brief      Free the memory allocated for a cpio handle.
 *
 * @param  cpio Handle obtained by calling cpio_start()
 *
 * @return
 *     - CPIO_RET_DONE on success
 *
 */
cpio_ret_t cpio_destroy(cpio_handle_t cpio);

#ifdef __cplusplus
}
#endif