CAN-binder/libs/nanopb/docs/migration.rst

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