Nicolas "Pixel" Noble | 39937f7 | 2016-09-23 06:28:04 +0200 | [diff] [blame] | 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 | |
Nicolas "Pixel" Noble | 87a1081 | 2016-09-29 01:31:54 +0200 | [diff] [blame] | 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 | |
Nicolas "Pixel" Noble | 39937f7 | 2016-09-23 06:28:04 +0200 | [diff] [blame] | 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 | |