1 /* 2 ** Copyright 2012-2013 Intel Corporation 3 ** 4 ** Licensed under the Apache License, Version 2.0 (the "License"); 5 ** you may not use this file except in compliance with the License. 6 ** You may obtain a copy of the License at 7 ** 8 ** http://www.apache.org/licenses/LICENSE-2.0 9 ** 10 ** Unless required by applicable law or agreed to in writing, software 11 ** distributed under the License is distributed on an "AS IS" BASIS, 12 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 ** See the License for the specific language governing permissions and 14 ** limitations under the License. 15 */ 16 17 /* 18 * \file libtbd.h 19 * \brief Tagged Binary Data handling 20 */ 21 22 #ifndef __LIBTBD_H__ 23 #define __LIBTBD_H__ 24 25 #include <stddef.h> /* defines size_t */ 26 #include <stdint.h> /* defines integer types with specified widths */ 27 #include <stdio.h> /* defines FILE */ 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /*! 34 * Revision of TBD System, format 0xYYMMDDVV, where: 35 * - YY: year, 36 * - MM: month, 37 * - DD: day, 38 * - VV: version ('01','02' etc.) 39 */ 40 #define IA_TBD_VERSION 0x12032201 41 42 /*! 43 * Revision of TBD data set, format 0xYYMMDDVV, where: 44 * - YY: year, 45 * - MM: month, 46 * - DD: day, 47 * - VV: version ('01','02' etc.) 48 */ 49 #define IA_TBD_REVISION 0x13091001 50 51 /*! 52 * \brief Error codes for libtbd. 53 */ 54 typedef enum 55 { 56 tbd_err_none = 0 , /*!< No errors */ 57 tbd_err_general = (1 << 1), /*!< General error */ 58 tbd_err_nomemory = (1 << 2), /*!< Out of memory */ 59 tbd_err_data = (1 << 3), /*!< Corrupted data */ 60 tbd_err_internal = (1 << 4), /*!< Error in code */ 61 tbd_err_argument = (1 << 5) /*!< Invalid argument for a function */ 62 } tbd_error_t; 63 64 /*! 65 * \brief Header structure for TBD container, followed by actual records. 66 */ 67 typedef struct 68 { 69 uint32_t tag; /*!< Tag identifier, also checks endianness */ 70 uint32_t size; /*!< Container size including this header */ 71 uint32_t version; /*!< Version of TBD system, format 0xYYMMDDVV */ 72 uint32_t revision; /*!< Revision of TBD data set, format 0xYYMMDDVV */ 73 uint32_t config_bits; /*!< Configuration flag bits set */ 74 uint32_t checksum; /*!< Global checksum, header included */ 75 } tbd_header_t; 76 77 /*! 78 * \brief Tag identifiers used in TBD container header. 79 */ 80 #define CHTOU32(a,b,c,d) ((uint32_t)(a)|((uint32_t)(b)<<8)|((uint32_t)(c)<<16)|((uint32_t)(d)<<24)) 81 typedef enum 82 { 83 tbd_tag_cpff = CHTOU32('C', 'P', 'F', 'F'), /*!< CPF File */ 84 tbd_tag_aiqb = CHTOU32('A', 'I', 'Q', 'B'), /*!< AIQ configuration */ 85 tbd_tag_aiqd = CHTOU32('A', 'I', 'Q', 'D'), /*!< AIQ data */ 86 tbd_tag_halb = CHTOU32('H', 'A', 'L', 'B'), /*!< CameraHAL configuration */ 87 tbd_tag_drvb = CHTOU32('D', 'R', 'V', 'B') /*!< Sensor driver configuration */ 88 } tbd_tag_t; 89 90 /*! 91 * \brief Record structure. Data is located right after this header. 92 */ 93 typedef struct 94 { 95 uint32_t size; /*!< Size of record including header */ 96 uint8_t format_id; /*!< tbd_format_t enumeration values used */ 97 uint8_t packing_key; /*!< Packing method; 0 = no packing */ 98 uint16_t class_id; /*!< tbd_class_t enumeration values used */ 99 } tbd_record_header_t; 100 101 /*! 102 * \brief Format ID enumeration describes the data format of the record. 103 */ 104 typedef enum 105 { 106 tbd_format_any = 0, /*!< Unspecified format */ 107 tbd_format_custom, /*!< User specified format */ 108 tbd_format_container /*!< Record is actually another TBD container */ 109 } tbd_format_t; 110 111 /*! 112 * \brief Class ID enumeration describes the data class of the record. 113 */ 114 typedef enum 115 { 116 tbd_class_any = 0, /*!< Unspecified record class */ 117 tbd_class_aiq, /*!< Used for AIC and 3A records */ 118 tbd_class_drv, /*!< Used for driver records */ 119 tbd_class_hal /*!< Used for HAL records */ 120 } tbd_class_t; 121 122 /*! 123 * \brief Creates a new Tagged Binary Data container. 124 * Creates a new, empty Tagged Binary Data container with the tag 125 * that was given. Also updates the checksum and size accordingly. 126 * Note that the buffer size must be large enough for the header 127 * to fit in, the exact amount being 24 bytes (for tbd_header_t). 128 * @param[in] a_data_ptr Pointer to modifiable container buffer 129 * @param[in] a_data_size Size of the container buffer 130 * @param[in] a_tag Tag the container shall have 131 * @param[out] a_new_size Updated container size 132 * @return Return code indicating possible errors 133 */ 134 tbd_error_t tbd_create(void *a_data_ptr, 135 size_t a_data_size, 136 tbd_tag_t a_tag, 137 size_t *a_new_size); 138 139 /*! 140 * \brief Checks if Tagged Binary Data is valid. All tags are accepted. 141 * Performs number of checks to given Tagged Binary Data container, 142 * including the verification of the checksum. The function does not 143 * care about the tag type of the container. 144 * @param[in] a_data_ptr Pointer to container buffer 145 * @param[in] a_data_size Size of the container buffer 146 * @return Return code indicating possible errors 147 */ 148 tbd_error_t tbd_validate_anytag(void *a_data_ptr, 149 size_t a_data_size); 150 151 /*! 152 * \brief Checks if Tagged Binary Data is valid, and tagged properly. 153 * Performs number of checks to given Tagged Binary Data container, 154 * including the verification of the checksum. Also, the data must have 155 * been tagged properly. The tag is further used to check endianness, 156 * and if it seems wrong, a specific debug message is printed out. 157 * @param[in] a_data_ptr Pointer to container buffer 158 * @param[in] a_data_size Size of the container buffer 159 * @param[in] a_tag Tag the data must have 160 * @return Return code indicating possible errors 161 */ 162 tbd_error_t tbd_validate(void *a_data_ptr, 163 size_t a_data_size, 164 tbd_tag_t a_tag); 165 166 /*! 167 * \brief Finds a record of given kind from within the container. 168 * Checks if a given kind of record exists in the Tagged Binary Data, 169 * and if yes, tells the location of such record as well as its size. 170 * If there are multiple records that match the query, the indicated 171 * record is the first one. 172 * @param[in] a_data_ptr Pointer to container buffer 173 * @param[in] a_record_class Class the record must have 174 * @param[in] a_record_format Format the record must have 175 * @param[out] a_record_data Record data (or NULL if not found) 176 * @param[out] a_record_size Record size (or 0 if not found) 177 * @return Return code indicating possible errors 178 */ 179 tbd_error_t tbd_get_record(void *a_data_ptr, 180 tbd_class_t a_record_class, 181 tbd_format_t a_record_format, 182 void **a_record_data, 183 uint32_t *a_record_size); 184 185 /*! 186 * \brief Updates the Tagged Binary Data with the given record inserted. 187 * The given record is inserted into the Tagged Binary Data container 188 * that must exist already. New records are always added to the end, 189 * regardless if a record with the same class and format field already 190 * exists in the data. Also updates the checksum and size accordingly. 191 * Note that the buffer size must be large enough for the inserted 192 * record to fit in, the exact amount being the size of original 193 * Tagged Binary Data container plus the size of record data to be 194 * inserted plus 8 bytes (for tbd_record_header_t). 195 * @param[in] a_data_ptr Pointer to modifiable container buffer 196 * @param[in] a_data_size Size of buffer (surplus included) 197 * @param[in] a_record_class Class the record shall have 198 * @param[in] a_record_format Format the record shall have 199 * @param[in] a_record_data Record data 200 * @param[in] a_record_size Record size 201 * @param[out] a_new_size Updated container size 202 * @return Return code indicating possible errors 203 */ 204 tbd_error_t tbd_insert_record(void *a_data_ptr, 205 size_t a_data_size, 206 tbd_class_t a_record_class, 207 tbd_format_t a_record_format, 208 void *a_record_data, 209 size_t a_record_size, 210 size_t *a_new_size); 211 212 /*! 213 * \brief Updates the Tagged Binary Data with the given record removed. 214 * The indicated record is removed from the Tagged Binary Data, after 215 * which the checksum and size are updated accordingly. If there are 216 * multiple records that match the class and format, only the first 217 * instance is removed. If no record is found, nothing will be done. 218 * Note that the resulting Tagged Binary Data container will 219 * be smaller than the original, but it does not harm to store the 220 * resulting container in its original length, either. 221 * @param[in] a_data_ptr Pointer to modifiable container buffer 222 * @param[in] a_record_class Class the record should have 223 * @param[in] a_record_format Format the record should have 224 * @param[out] a_new_size Updated container size 225 * @return Return code indicating possible errors 226 */ 227 tbd_error_t tbd_remove_record(void *a_data_ptr, 228 tbd_class_t a_record_class, 229 tbd_format_t a_record_format, 230 size_t *a_new_size); 231 232 /*! 233 * \brief Writes all possible information about the Tagged Binary Data. 234 * Validates the Tagged Binary data container and generates a human 235 * readable detailed report on the content, including information about 236 * the records contained. 237 * @param[in] a_data_ptr Pointer to container buffer 238 * @param[in] a_data_size Size of the container buffer 239 * @param[in] a_outfile Pointer to open file (may be stdout) 240 * @return Return code indicating possible errors 241 */ 242 tbd_error_t tbd_infoprint(void *a_data_ptr, 243 size_t a_data_size, 244 FILE *a_outfile); 245 246 #ifdef __cplusplus 247 } 248 #endif 249 250 #endif /* __LIBTBD_H__ */ 251