1 ===================================== 2 Nanopb: Migration from older versions 3 ===================================== 4 5 .. include :: menu.rst 6 7 This document details all the breaking changes that have been made to nanopb 8 since its initial release. For each change, the rationale and required 9 modifications of user applications are explained. Also any error indications 10 are included, in order to make it easier to find this document. 11 12 .. contents :: 13 14 Nanopb-0.3.5 (2016-02-13) 15 ========================= 16 17 Add support for platforms without uint8_t 18 ----------------------------------------- 19 **Rationale:** Some platforms cannot access 8-bit sized values directly, and 20 do not define *uint8_t*. Nanopb previously didn't support these platforms. 21 22 **Changes:** References to *uint8_t* were replaced with several alternatives, 23 one of them being a new *pb_byte_t* typedef. This in turn uses *uint_least8_t* 24 which means the smallest available type. 25 26 **Required actions:** If your platform does not have a standards-compliant 27 *stdint.h*, it may lack the definition for *[u]int_least8_t*. This must be 28 added manually, example can be found in *extra/pb_syshdr.h*. 29 30 **Error indications:** Compiler error: "unknown type name 'uint_least8_t'". 31 32 Nanopb-0.3.2 (2015-01-24) 33 ========================= 34 35 Add support for OneOfs 36 ---------------------- 37 **Rationale:** Previously nanopb did not support the *oneof* construct in 38 *.proto* files. Those fields were generated as regular *optional* fields. 39 40 **Changes:** OneOfs are now generated as C unions. Callback fields are not 41 supported inside oneof and generator gives an error. 42 43 **Required actions:** The generator option *no_unions* can be used to restore old 44 behaviour and to allow callbacks to be used. To use unions, one change is 45 needed: use *which_xxxx* field to detect which field is present, instead 46 of *has_xxxx*. Compare the value against *MyStruct_myfield_tag*. 47 48 **Error indications:** Generator error: "Callback fields inside of oneof are 49 not supported". Compiler error: "Message" has no member named "has_xxxx". 50 51 Nanopb-0.3.0 (2014-08-26) 52 ========================= 53 54 Separate field iterator logic to pb_common.c 55 -------------------------------------------- 56 **Rationale:** Originally, the field iteration logic was simple enough to be 57 duplicated in *pb_decode.c* and *pb_encode.c*. New field types have made the 58 logic more complex, which required the creation of a new file to contain the 59 common functionality. 60 61 **Changes:** There is a new file, *pb_common.c*, which must be included in 62 builds. 63 64 **Required actions:** Add *pb_common.c* to build rules. This file is always 65 required. Either *pb_decode.c* or *pb_encode.c* can still be left out if some 66 functionality is not needed. 67 68 **Error indications:** Linker error: undefined reference to 69 *pb_field_iter_begin*, *pb_field_iter_next* or similar. 70 71 Change data type of field counts to pb_size_t 72 --------------------------------------------- 73 **Rationale:** Often nanopb is used with small arrays, such as 255 items or 74 less. Using a full *size_t* field to store the array count wastes memory if 75 there are many arrays. There already exists parameters *PB_FIELD_16BIT* and 76 *PB_FIELD_32BIT* which tell nanopb what is the maximum size of arrays in use. 77 78 **Changes:** Generator will now use *pb_size_t* for the array *_count* fields. 79 The size of the type will be controlled by the *PB_FIELD_16BIT* and 80 *PB_FIELD_32BIT* compilation time options. 81 82 **Required actions:** Regenerate all *.pb.h* files. In some cases casts to the 83 *pb_size_t* type may need to be added in the user code when accessing the 84 *_count* fields. 85 86 **Error indications:** Incorrect data at runtime, crashes. But note that other 87 changes in the same version already require regenerating the files and have 88 better indications of errors, so this is only an issue for development 89 versions. 90 91 Renamed some macros and identifiers 92 ----------------------------------- 93 **Rationale:** Some names in nanopb core were badly chosen and conflicted with 94 ISO C99 reserved names or lacked a prefix. While they haven't caused trouble 95 so far, it is reasonable to switch to non-conflicting names as these are rarely 96 used from user code. 97 98 **Changes:** The following identifier names have changed: 99 100 * Macros: 101 102 * STATIC_ASSERT(x) -> PB_STATIC_ASSERT(x) 103 * UNUSED(x) -> PB_UNUSED(x) 104 105 * Include guards: 106 107 * _PB_filename_ -> PB_filename_INCLUDED 108 109 * Structure forward declaration tags: 110 111 * _pb_field_t -> pb_field_s 112 * _pb_bytes_array_t -> pb_bytes_array_s 113 * _pb_callback_t -> pb_callback_s 114 * _pb_extension_type_t -> pb_extension_type_s 115 * _pb_extension_t -> pb_extension_s 116 * _pb_istream_t -> pb_istream_s 117 * _pb_ostream_t -> pb_ostream_s 118 119 **Required actions:** Regenerate all *.pb.c* files. If you use any of the above 120 identifiers in your application code, perform search-replace to the new name. 121 122 **Error indications:** Compiler errors on lines with the macro/type names. 123 124 Nanopb-0.2.9 (2014-08-09) 125 ========================= 126 127 Change semantics of generator -e option 128 --------------------------------------- 129 **Rationale:** Some compilers do not accept filenames with two dots (like 130 in default extension .pb.c). The *-e* option to the generator allowed changing 131 the extension, but not skipping the extra dot. 132 133 **Changes:** The *-e* option in generator will no longer add the prepending 134 dot. The default value has been adjusted accordingly to *.pb.c* to keep the 135 default behaviour the same as before. 136 137 **Required actions:** Only if using the generator -e option. Add dot before 138 the parameter value on the command line. 139 140 **Error indications:** File not found when trying to compile generated files. 141 142 Nanopb-0.2.7 (2014-04-07) 143 ========================= 144 145 Changed pointer-type bytes field datatype 146 ----------------------------------------- 147 **Rationale:** In the initial pointer encoding support since nanopb-0.2.5, 148 the bytes type used a separate *pb_bytes_ptr_t* type to represent *bytes* 149 fields. This made it easy to encode data from a separate, user-allocated 150 buffer. However, it made the internal logic more complex and was inconsistent 151 with the other types. 152 153 **Changes:** Dynamically allocated bytes fields now have the *pb_bytes_array_t* 154 type, just like statically allocated ones. 155 156 **Required actions:** Only if using pointer-type fields with the bytes datatype. 157 Change any access to *msg->field.size* to *msg->field->size*. Change any 158 allocation to reserve space of amount *PB_BYTES_ARRAY_T_ALLOCSIZE(n)*. If the 159 data pointer was begin assigned from external source, implement the field using 160 a callback function instead. 161 162 **Error indications:** Compiler error: unknown type name *pb_bytes_ptr_t*. 163 164 Nanopb-0.2.4 (2013-11-07) 165 ========================= 166 167 Remove the NANOPB_INTERNALS compilation option 168 ---------------------------------------------- 169 **Rationale:** Having the option in the headers required the functions to 170 be non-static, even if the option is not used. This caused errors on some 171 static analysis tools. 172 173 **Changes:** The *#ifdef* and associated functions were removed from the 174 header. 175 176 **Required actions:** Only if the *NANOPB_INTERNALS* option was previously 177 used. Actions are as listed under nanopb-0.1.3 and nanopb-0.1.6. 178 179 **Error indications:** Compiler warning: implicit declaration of function 180 *pb_dec_string*, *pb_enc_string*, or similar. 181 182 Nanopb-0.2.1 (2013-04-14) 183 ========================= 184 185 Callback function signature 186 --------------------------- 187 **Rationale:** Previously the auxilary data to field callbacks was passed 188 as *void\**. This allowed passing of any data, but made it unnecessarily 189 complex to return a pointer from callback. 190 191 **Changes:** The callback function parameter was changed to *void\*\**. 192 193 **Required actions:** You can continue using the old callback style by 194 defining *PB_OLD_CALLBACK_STYLE*. Recommended action is to: 195 196 * Change the callback signatures to contain *void\*\** for decoders and 197 *void \* const \** for encoders. 198 * Change the callback function body to use *\*arg* instead of *arg*. 199 200 **Error indications:** Compiler warning: assignment from incompatible 201 pointer type, when initializing *funcs.encode* or *funcs.decode*. 202 203 Nanopb-0.2.0 (2013-03-02) 204 ========================= 205 206 Reformatted generated .pb.c file using macros 207 --------------------------------------------- 208 **Rationale:** Previously the generator made a list of C *pb_field_t* 209 initializers in the .pb.c file. This led to a need to regenerate all .pb.c 210 files after even small changes to the *pb_field_t* definition. 211 212 **Changes:** Macros were added to pb.h which allow for cleaner definition 213 of the .pb.c contents. By changing the macro definitions, changes to the 214 field structure are possible without breaking compatibility with old .pb.c 215 files. 216 217 **Required actions:** Regenerate all .pb.c files from the .proto sources. 218 219 **Error indications:** Compiler warning: implicit declaration of function 220 *pb_delta_end*. 221 222 Changed pb_type_t definitions 223 ----------------------------- 224 **Rationale:** The *pb_type_t* was previously an enumeration type. This 225 caused warnings on some compilers when using bitwise operations to set flags 226 inside the values. 227 228 **Changes:** The *pb_type_t* was changed to *typedef uint8_t*. The values 229 were changed to *#define*. Some value names were changed for consistency. 230 231 **Required actions:** Only if you directly access the `pb_field_t` contents 232 in your own code, something which is not usually done. Needed changes: 233 234 * Change *PB_HTYPE_ARRAY* to *PB_HTYPE_REPEATED*. 235 * Change *PB_HTYPE_CALLBACK* to *PB_ATYPE()* and *PB_ATYPE_CALLBACK*. 236 237 **Error indications:** Compiler error: *PB_HTYPE_ARRAY* or *PB_HTYPE_CALLBACK* 238 undeclared. 239 240 Nanopb-0.1.6 (2012-09-02) 241 ========================= 242 243 Refactored field decoder interface 244 ---------------------------------- 245 **Rationale:** Similarly to field encoders in nanopb-0.1.3. 246 247 **Changes:** New functions with names *pb_decode_\** were added. 248 249 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using 250 the old functions. Recommended action is to replace any calls with the newer 251 *pb_decode_\** equivalents. 252 253 **Error indications:** Compiler warning: implicit declaration of function 254 *pb_dec_string*, *pb_dec_varint*, *pb_dec_submessage* or similar. 255 256 Nanopb-0.1.3 (2012-06-12) 257 ========================= 258 259 Refactored field encoder interface 260 ---------------------------------- 261 **Rationale:** The old *pb_enc_\** functions were designed mostly for the 262 internal use by the core. Because they are internally accessed through 263 function pointers, their signatures had to be common. This led to a confusing 264 interface for external users. 265 266 **Changes:** New functions with names *pb_encode_\** were added. These have 267 easier to use interfaces. The old functions are now only thin wrappers for 268 the new interface. 269 270 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using 271 the old functions. Recommended action is to replace any calls with the newer 272 *pb_encode_\** equivalents. 273 274 **Error indications:** Compiler warning: implicit declaration of function 275 *pb_enc_string*, *pb_enc_varint, *pb_enc_submessage* or similar. 276 277
