/* IBM_PROLOG_BEGIN_TAG */ /* This is an automatically generated prolog. */ /* */ /* $Source: ffs/libffs2.h $ */ /* */ /* OpenPOWER FFS Project */ /* */ /* Contributors Listed Below - COPYRIGHT 2014,2015 */ /* [+] International Business Machines Corp. */ /* */ /* */ /* 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. */ /* */ /* IBM_PROLOG_END_TAG */ /*! * @file libffs2.h * @brief FSP Flash File Structure API * @details This library provides an API to the FFS partitioning scheme. * @author Shaun Wetzstein * @date 2010-2012 */ #ifndef __LIBFFS2_H__ #define __LIBFFS2_H__ #ifdef __cplusplus extern "C" { #endif #include "libffs.h" /* FFS_OPEN_* are deprecated, use FFS_CHECK_* instead */ #define FFS_OPEN_INVALID_PATH FFS_CHECK_PATH #define FFS_OPEN_FOPEN_FAILURE -1 #define FFS_OPEN_MAGIC_CHECK FFS_CHECK_HEADER_MAGIC #define FFS_OPEN_CRC_CHECK FFS_CHECK_HEADER_CHECKSUM /*! * @brief Clears the (global) FFS error indicator * @memberof ffs * @return None */ extern void ffs_errclr(void); /*! * @brief Return the error number of an FFS error * @memberof ffs * @return non-0 on success, '0' if no pending error */ extern int ffs_errnum(void); /*! * @brief Return the error string of an FFS error * @memberof ffs * @return non-NULL on success, 'NULL' if no pending error */ extern const char * ffs_errstr(void); /*! * @brief Open the file named 'path' and check the @em FFS partition table * at 'offset' bytes from the beginning of the file (or device). * @memberof ffs * @param path [in] Path of target file or device * @param offset [in] Byte offset, from the beginning of the file (or device), * of the ffs_hdr_t structure * @return 0 on success, non-0 otherwise * FFS_CHECK_PATH if path is NULL or "" * FFS_CHECK_HEADER_MAGIC for header magic corruption * FFS_CHECK_HEADER_CHECKSUM for header data corruption * FFS_CHECK_ENTRY_CHECKSUM for [an] entry data corruption */ extern int ffs_check(const char *, off_t) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Create an empty @em FFS partition table and store it at 'offset' * bytes from the beginning of the file (or device) named 'path' * @memberof ffs * @param path [in] Path of target file or device * @param offset [in] Byte offset, from beginning of file (or device), * of the ffs_hdr_t structure * @param block_size [in] Block size in bytes * @param block_count [in] Number of blocks in the device size * @return Pointer to ffs_t (allocated on the heap) on success, * NULL otherwise */ extern ffs_t * ffs_create(const char *, off_t, uint32_t, uint32_t) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Open the file name 'path' and read the @em FFS partition table * at 'offset' bytes from the beggining of the file (or device). * @memberof ffs * @param path [in] Path of target file or device * @param offset [in] Byte offset, from beginning of file (or device), * of the ffs_hdr_t structure * @return Pointer to ffs_t (allocated on the heap) on success, * NULL otherwise */ extern ffs_t * ffs_open(const char *, off_t) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Query a @em FFS object for header metadata. * @memberof ffs * @param self [in] Pointer to ffs object * @param name [in] Field number, see ffs.h for details * FFS_INFO_MAGIC - ffs_hdr::magic * FFS_INFO_VERSION - ffs_hdr::version * FFS_INFO_ENTRY_SIZE - ffs_hdr::entry_size * FFS_INFO_ENTRY_COUNT - ffs_hdr::entry_count * FFS_INFO_BLOCK_SIZE - ffs_hdr::block_size * FFS_INFO_BLOCK_COUNT - ffs_hdr::block_count * @param value [out] Pointer to output data * @return '0' on success, non-0 otherwise */ extern int ffs_info(ffs_t *, int, uint32_t *) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Close a @em FFS object, after writting any modified in-core * data to the file (or device). * @memberof ffs * @param self [in] Pointer to ffs object * @return '0' on success, non-0 otherwise */ extern int ffs_close(ffs_t *) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Flush all modified in-core metadata of a @em FFS object, * to the underlying file (or device). * @memberof ffs * @param self [in] Pointer to ffs object * @return '0' on success, non-0 otherwise */ extern int ffs_fsync(ffs_t *) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Pretty print the entries of a @em FFS partition table to * stream 'out' * @memberof ffs * @param self [in] Pointer to ffs object * @param out [in] Pointer the output stream * @return '0' on success, non-0 otherwise */ extern int ffs_list_entries(ffs_t *, FILE *) /*! @cond */ __nonnull ((1)) /*! @endcond */ ; /*! * @brief Iterate over the entries of a @em FFS partition table and * call a callback function 'func' * @note If the callback function returns non-0, the iteration function * will return immediately. * @memberof ffs * @param self [in] Pointer to ffs object * @param func [in] Pointer the callback function * @return '0' on success, non-0 otherwise */ extern int ffs_iterate_entries(ffs_t *, int (*)(ffs_entry_t*)) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Find an entry in a @em FFS partition table and return * a copy of the in 'entry' * @memberof ffs * @param self [in] Pointer to ffs object * @param path [in] Name of a partition entry * @param entry [out] Target entry object * @return '1' == found, '0' == not-found, error otherwise */ extern int ffs_entry_find(ffs_t *, const char *, ffs_entry_t *) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Find the parent entry in a @em FFS partition table and * return a copy of the in 'entry' * @memberof ffs * @param self [in] Pointer to ffs object * @param path [in] Name of a partition entry * @param parent [out] Target entry object * @return '1' == found, '0' == not-found, error otherwise */ extern int ffs_entry_find_parent(ffs_t *, const char *, ffs_entry_t *) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Add a partition entry to a @em FFS partition table * @memberof ffs * @param self [in] Pointer to ffs object * @param path [in] Name of a partition entry * @param offset [in] Offset, in blocks, of the partition entry, from * the beginning of the file (or device) * @param size [in] Size, in blocks, of the partition entry * @param type [in] Partition type. FFS_TYPE_LOGICAL can be used to * to create a container for a set of partitions. A logical partition * can be thought of as a directory. Use FFS_TYPE_DATA for data * partitions. * @param flags [in] Partition flags. FFS_FLAG_PROTECTED can be used to * protect a partition from inadvertant updates. The ffs related tools * should *not* overwrite protected partitions unless a --protected * flag is specified. * @return '0' on success, non-0 otherwise */ extern int ffs_entry_add(ffs_t *, const char *, off_t, size_t, ffs_type_t, uint32_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Delete a partition entry from the @em FFS partition table * @memberof ffs * @param self [in] Pointer to an ffs object * @param path [in] Name of a partition entry * @return '0' on success, non-0 otherwise */ extern int ffs_entry_delete(ffs_t *, const char *) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Get the value of a meta-data user word * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param user [in] User word number, in the range [0..FFS_USER_WORDS] * @param word [in] User word value, in the range [0..UINT32_MAX] (optional) * @note 'word' is optional, if omitted, the current value is returned * @return '0' on success, non-0 otherwise */ extern int ffs_entry_user_get(ffs_t *, const char *, uint32_t, uint32_t *) /*! @cond */ __nonnull ((1,2,4)) /*! @endcond */ ; /*! * @brief Set the value of a meta-data user word * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param user [in] User word number, in the range [0..FFS_USER_WORDS] * @param word [in] User word value, in the range [0..UINT32_MAX] (optional) * @note 'word' is optional, if omitted, the current value is returned * @return '0' on success, non-0 otherwise */ extern int ffs_entry_user_put(ffs_t *, const char *, uint32_t, uint32_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Hexdump the data contents of a partition entry to output stream * 'out' * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param out [in] Output stream * @return Negative on success, number of bytes written otherwise */ extern ssize_t ffs_entry_hexdump(ffs_t *, const char *, FILE *) /*! @cond */ __nonnull ((1,2,3)) /*! @endcond */ ; /*! * @brief Change the actual size of partition entry 'name' * to 'offset' bytes from the beginning of the entry. * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param offset [in] Offset from the beginning of the partition (in bytes) * @return Negative on failure, zero otherwise */ extern ssize_t ffs_entry_truncate_no_pad(ffs_t *, const char *, off_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Change the actual size of partition entry 'name' * to 'offset' bytes from the beginning of the entry. * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param offset [in] Offset from the beginning of the partition (in bytes) * @param pad [in] Pad character * @return Negative on failure, zero otherwise */ extern ssize_t ffs_entry_truncate(ffs_t *, const char *, off_t, uint8_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Read 'count' data bytes of partition entry 'name' to into 'buf' at * offset 'offset' bytes from the beginning of the entry * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param buf [out] Output data buffer * @param offset [in] Offset from the beginning of the partition * @param count [in] Number of bytes to read * @return Negative on failure, number of bytes read otherwise */ extern ssize_t ffs_entry_read(ffs_t *, const char *, void *, off_t, size_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Write 'count' data bytes to partition entry 'name' at offset * 'offset' bytes from the beginning of the entry, from input * buffer 'buf' * @memberof ffs * @param self [in] Pointer to an ffs object * @param name [in] Name of a partition entry * @param buf [in] Input data buffer * @param offset [in] Offset from the beginning of the partition * @param count [in] Number of bytes to write * @return Negative on failure, else number of bytes written otherwise */ extern ssize_t ffs_entry_write(ffs_t *, const char *, const void *, off_t, size_t) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; /*! * @brief Return an array of entry_t structures, one each partition that * exists in the partition table * @memberof ffs * @param self [in] Pointer to an ffs object * @param list [out] Array of entry_t structures allocated on the heap * @return Negative on failure, else number of entry_t's in the output * array with a call to free() * @note Caller is responsible for freeing array with a call to free() */ extern ssize_t ffs_entry_list(ffs_t *, ffs_entry_t **) /*! @cond */ __nonnull ((1,2)) /*! @endcond */ ; #ifdef __cplusplus } #endif #endif /* __LIBFFS2_H__ */