| /* |
| ** Copyright 2012-2013 Intel Corporation |
| ** |
| ** 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. |
| */ |
| |
| /* |
| * \file libtbd.h |
| * \brief Tagged Binary Data handling |
| */ |
| |
| #ifndef __LIBTBD_H__ |
| #define __LIBTBD_H__ |
| |
| #include <stddef.h> /* defines size_t */ |
| #include <stdint.h> /* defines integer types with specified widths */ |
| #include <stdio.h> /* defines FILE */ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /*! |
| * Revision of TBD System, format 0xYYMMDDVV, where: |
| * - YY: year, |
| * - MM: month, |
| * - DD: day, |
| * - VV: version ('01','02' etc.) |
| */ |
| #define IA_TBD_VERSION 0x12032201 |
| |
| /*! |
| * Revision of TBD data set, format 0xYYMMDDVV, where: |
| * - YY: year, |
| * - MM: month, |
| * - DD: day, |
| * - VV: version ('01','02' etc.) |
| */ |
| #define IA_TBD_REVISION 0x13091001 |
| |
| /*! |
| * \brief Error codes for libtbd. |
| */ |
| typedef enum |
| { |
| tbd_err_none = 0 , /*!< No errors */ |
| tbd_err_general = (1 << 1), /*!< General error */ |
| tbd_err_nomemory = (1 << 2), /*!< Out of memory */ |
| tbd_err_data = (1 << 3), /*!< Corrupted data */ |
| tbd_err_internal = (1 << 4), /*!< Error in code */ |
| tbd_err_argument = (1 << 5) /*!< Invalid argument for a function */ |
| } tbd_error_t; |
| |
| /*! |
| * \brief Header structure for TBD container, followed by actual records. |
| */ |
| typedef struct |
| { |
| uint32_t tag; /*!< Tag identifier, also checks endianness */ |
| uint32_t size; /*!< Container size including this header */ |
| uint32_t version; /*!< Version of TBD system, format 0xYYMMDDVV */ |
| uint32_t revision; /*!< Revision of TBD data set, format 0xYYMMDDVV */ |
| uint32_t config_bits; /*!< Configuration flag bits set */ |
| uint32_t checksum; /*!< Global checksum, header included */ |
| } tbd_header_t; |
| |
| /*! |
| * \brief Tag identifiers used in TBD container header. |
| */ |
| #define CHTOU32(a,b,c,d) ((uint32_t)(a)|((uint32_t)(b)<<8)|((uint32_t)(c)<<16)|((uint32_t)(d)<<24)) |
| typedef enum |
| { |
| tbd_tag_cpff = CHTOU32('C', 'P', 'F', 'F'), /*!< CPF File */ |
| tbd_tag_aiqb = CHTOU32('A', 'I', 'Q', 'B'), /*!< AIQ configuration */ |
| tbd_tag_aiqd = CHTOU32('A', 'I', 'Q', 'D'), /*!< AIQ data */ |
| tbd_tag_halb = CHTOU32('H', 'A', 'L', 'B'), /*!< CameraHAL configuration */ |
| tbd_tag_drvb = CHTOU32('D', 'R', 'V', 'B') /*!< Sensor driver configuration */ |
| } tbd_tag_t; |
| |
| /*! |
| * \brief Record structure. Data is located right after this header. |
| */ |
| typedef struct |
| { |
| uint32_t size; /*!< Size of record including header */ |
| uint8_t format_id; /*!< tbd_format_t enumeration values used */ |
| uint8_t packing_key; /*!< Packing method; 0 = no packing */ |
| uint16_t class_id; /*!< tbd_class_t enumeration values used */ |
| } tbd_record_header_t; |
| |
| /*! |
| * \brief Format ID enumeration describes the data format of the record. |
| */ |
| typedef enum |
| { |
| tbd_format_any = 0, /*!< Unspecified format */ |
| tbd_format_custom, /*!< User specified format */ |
| tbd_format_container /*!< Record is actually another TBD container */ |
| } tbd_format_t; |
| |
| /*! |
| * \brief Class ID enumeration describes the data class of the record. |
| */ |
| typedef enum |
| { |
| tbd_class_any = 0, /*!< Unspecified record class */ |
| tbd_class_aiq, /*!< Used for AIC and 3A records */ |
| tbd_class_drv, /*!< Used for driver records */ |
| tbd_class_hal /*!< Used for HAL records */ |
| } tbd_class_t; |
| |
| /*! |
| * \brief Creates a new Tagged Binary Data container. |
| * Creates a new, empty Tagged Binary Data container with the tag |
| * that was given. Also updates the checksum and size accordingly. |
| * Note that the buffer size must be large enough for the header |
| * to fit in, the exact amount being 24 bytes (for tbd_header_t). |
| * @param[in] a_data_ptr Pointer to modifiable container buffer |
| * @param[in] a_data_size Size of the container buffer |
| * @param[in] a_tag Tag the container shall have |
| * @param[out] a_new_size Updated container size |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_create(void *a_data_ptr, |
| size_t a_data_size, |
| tbd_tag_t a_tag, |
| size_t *a_new_size); |
| |
| /*! |
| * \brief Checks if Tagged Binary Data is valid. All tags are accepted. |
| * Performs number of checks to given Tagged Binary Data container, |
| * including the verification of the checksum. The function does not |
| * care about the tag type of the container. |
| * @param[in] a_data_ptr Pointer to container buffer |
| * @param[in] a_data_size Size of the container buffer |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_validate_anytag(void *a_data_ptr, |
| size_t a_data_size); |
| |
| /*! |
| * \brief Checks if Tagged Binary Data is valid, and tagged properly. |
| * Performs number of checks to given Tagged Binary Data container, |
| * including the verification of the checksum. Also, the data must have |
| * been tagged properly. The tag is further used to check endianness, |
| * and if it seems wrong, a specific debug message is printed out. |
| * @param[in] a_data_ptr Pointer to container buffer |
| * @param[in] a_data_size Size of the container buffer |
| * @param[in] a_tag Tag the data must have |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_validate(void *a_data_ptr, |
| size_t a_data_size, |
| tbd_tag_t a_tag); |
| |
| /*! |
| * \brief Finds a record of given kind from within the container. |
| * Checks if a given kind of record exists in the Tagged Binary Data, |
| * and if yes, tells the location of such record as well as its size. |
| * If there are multiple records that match the query, the indicated |
| * record is the first one. |
| * @param[in] a_data_ptr Pointer to container buffer |
| * @param[in] a_record_class Class the record must have |
| * @param[in] a_record_format Format the record must have |
| * @param[out] a_record_data Record data (or NULL if not found) |
| * @param[out] a_record_size Record size (or 0 if not found) |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_get_record(void *a_data_ptr, |
| tbd_class_t a_record_class, |
| tbd_format_t a_record_format, |
| void **a_record_data, |
| uint32_t *a_record_size); |
| |
| /*! |
| * \brief Updates the Tagged Binary Data with the given record inserted. |
| * The given record is inserted into the Tagged Binary Data container |
| * that must exist already. New records are always added to the end, |
| * regardless if a record with the same class and format field already |
| * exists in the data. Also updates the checksum and size accordingly. |
| * Note that the buffer size must be large enough for the inserted |
| * record to fit in, the exact amount being the size of original |
| * Tagged Binary Data container plus the size of record data to be |
| * inserted plus 8 bytes (for tbd_record_header_t). |
| * @param[in] a_data_ptr Pointer to modifiable container buffer |
| * @param[in] a_data_size Size of buffer (surplus included) |
| * @param[in] a_record_class Class the record shall have |
| * @param[in] a_record_format Format the record shall have |
| * @param[in] a_record_data Record data |
| * @param[in] a_record_size Record size |
| * @param[out] a_new_size Updated container size |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_insert_record(void *a_data_ptr, |
| size_t a_data_size, |
| tbd_class_t a_record_class, |
| tbd_format_t a_record_format, |
| void *a_record_data, |
| size_t a_record_size, |
| size_t *a_new_size); |
| |
| /*! |
| * \brief Updates the Tagged Binary Data with the given record removed. |
| * The indicated record is removed from the Tagged Binary Data, after |
| * which the checksum and size are updated accordingly. If there are |
| * multiple records that match the class and format, only the first |
| * instance is removed. If no record is found, nothing will be done. |
| * Note that the resulting Tagged Binary Data container will |
| * be smaller than the original, but it does not harm to store the |
| * resulting container in its original length, either. |
| * @param[in] a_data_ptr Pointer to modifiable container buffer |
| * @param[in] a_record_class Class the record should have |
| * @param[in] a_record_format Format the record should have |
| * @param[out] a_new_size Updated container size |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_remove_record(void *a_data_ptr, |
| tbd_class_t a_record_class, |
| tbd_format_t a_record_format, |
| size_t *a_new_size); |
| |
| /*! |
| * \brief Writes all possible information about the Tagged Binary Data. |
| * Validates the Tagged Binary data container and generates a human |
| * readable detailed report on the content, including information about |
| * the records contained. |
| * @param[in] a_data_ptr Pointer to container buffer |
| * @param[in] a_data_size Size of the container buffer |
| * @param[in] a_outfile Pointer to open file (may be stdout) |
| * @return Return code indicating possible errors |
| */ |
| tbd_error_t tbd_infoprint(void *a_data_ptr, |
| size_t a_data_size, |
| FILE *a_outfile); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* __LIBTBD_H__ */ |