diff options
| -rw-r--r-- | docs/Makefile | 2 | ||||
| -rw-r--r-- | docs/menu.rst | 2 | ||||
| -rw-r--r-- | docs/migration.rst | 186 |
3 files changed, 189 insertions, 1 deletions
diff --git a/docs/Makefile b/docs/Makefile index e7143b25..0dbd97cf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,4 +1,4 @@ -all: index.html concepts.html reference.html security.html \ +all: index.html concepts.html reference.html security.html migration.html \ generator_flow.png %.png: %.svg diff --git a/docs/menu.rst b/docs/menu.rst index a49b22c1..2c110def 100644 --- a/docs/menu.rst +++ b/docs/menu.rst @@ -4,8 +4,10 @@ 2) `Concepts`_ 3) `API reference`_ 4) `Security model`_ + 5) `Migration from older versions`_ .. _`Overview`: index.html .. _`Concepts`: concepts.html .. _`API reference`: reference.html .. _`Security model`: security.html +.. _`Migration from older versions`: migration.html diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 00000000..9d41f5b1 --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1,186 @@ +===================================== +Nanopb: Migration from older versions +===================================== + +.. include :: menu.rst + +This document details all the breaking changes that have been made to nanopb +since its initial release. For each change, the rationale and required +modifications of user applications are explained. Also any error indications +are included, in order to make it easier to find this document. + +.. contents :: + +Nanopb-0.3.0 (2014-09-xx) +========================= + +Separate field iterator logic to pb_common.c +-------------------------------------------- +**Rationale:** Originally, the field iteration logic was simple enough to be +duplicated in *pb_decode.c* and *pb_encode.c*. New field types have made the +logic more complex, which required the creation of a new file to contain the +common functionality. + +**Changes:** There is a new file, *pb_common.c*, which must be included in +builds. + +**Required actions:** Add *pb_common.c* to build rules. This file is always +required. Either *pb_decode.c* or *pb_encode.c* can still be left out if some +functionality is not needed. + +**Error indications:** Linker error: undefined reference to +*pb_field_iter_begin*, *pb_field_iter_next* or similar. + +Nanopb-0.2.9 (2014-08-09) +========================= + +Change semantics of generator -e option +--------------------------------------- +**Rationale:** Some compilers do not accept filenames with two dots (like +in default extension .pb.c). The *-e* option to the generator allowed changing +the extension, but not skipping the extra dot. + +**Changes:** The *-e* option in generator will no longer add the prepending +dot. The default value has been adjusted accordingly to *.pb.c* to keep the +default behaviour the same as before. + +**Required actions:** Only if using the generator -e option. Add dot before +the parameter value on the command line. + +**Error indications:** File not found when trying to compile generated files. + +Nanopb-0.2.7 (2014-04-07) +========================= + +Changed pointer-type bytes field datatype +----------------------------------------- +**Rationale:** In the initial pointer encoding support since nanopb-0.2.5, +the bytes type used a separate *pb_bytes_ptr_t* type to represent *bytes* +fields. This made it easy to encode data from a separate, user-allocated +buffer. However, it made the internal logic more complex and was inconsistent +with the other types. + +**Changes:** Dynamically allocated bytes fields now have the *pb_bytes_array_t* +type, just like statically allocated ones. + +**Required actions:** Only if using pointer-type fields with the bytes datatype. +Change any access to *msg->field.size* to *msg->field->size*. Change any +allocation to reserve space of amount *PB_BYTES_ARRAY_T_ALLOCSIZE(n)*. If the +data pointer was begin assigned from external source, implement the field using +a callback function instead. + +**Error indications:** Compiler error: unknown type name *pb_bytes_ptr_t*. + +Nanopb-0.2.4 (2013-11-07) +========================= + +Remove the NANOPB_INTERNALS compilation option +---------------------------------------------- +**Rationale:** Having the option in the headers required the functions to +be non-static, even if the option is not used. This caused errors on some +static analysis tools. + +**Changes:** The *#ifdef* and associated functions were removed from the +header. + +**Required actions:** Only if the *NANOPB_INTERNALS* option was previously +used. Actions are as listed under nanopb-0.1.3 and nanopb-0.1.6. + +**Error indications:** Compiler warning: implicit declaration of function +*pb_dec_string*, *pb_enc_string*, or similar. + +Nanopb-0.2.1 (2013-04-14) +========================= + +Callback function signature +--------------------------- +**Rationale:** Previously the auxilary data to field callbacks was passed +as *void\**. This allowed passing of any data, but made it unnecessarily +complex to return a pointer from callback. + +**Changes:** The callback function parameter was changed to *void\**. + +**Required actions:** You can continue using the old callback style by +defining *PB_OLD_CALLBACK_STYLE*. Recommended action is to: + + * Change the callback signatures to contain *void\** for decoders and + *void \* const \** for encoders. + * Change the callback function body to use *\*arg* instead of *arg*. + +**Error indications:** Compiler warning: assignment from incompatible +pointer type, when initializing *funcs.encode* or *funcs.decode*. + +Nanopb-0.2.0 (2013-03-02) +========================= + +Reformatted generated .pb.c file using macros +--------------------------------------------- +**Rationale:** Previously the generator made a list of C *pb_field_t* +initializers in the .pb.c file. This led to a need to regenerate all .pb.c +files after even small changes to the *pb_field_t* definition. + +**Changes:** Macros were added to pb.h which allow for cleaner definition +of the .pb.c contents. By changing the macro definitions, changes to the +field structure are possible without breaking compatibility with old .pb.c +files. + +**Required actions:** Regenerate all .pb.c files from the .proto sources. + +**Error indications:** Compiler warning: implicit declaration of function +*pb_delta_end*. + +Changed pb_type_t definitions +----------------------------- +**Rationale:** The *pb_type_t* was previously an enumeration type. This +caused warnings on some compilers when using bitwise operations to set flags +inside the values. + +**Changes:** The *pb_type_t* was changed to *typedef uint8_t*. The values +were changed to *#define*. Some value names were changed for consistency. + +**Required actions:** Only if you directly access the `pb_field_t` contents +in your own code, something which is not usually done. Needed changes: + + * Change *PB_HTYPE_ARRAY* to *PB_HTYPE_REPEATED*. + * Change *PB_HTYPE_CALLBACK* to *PB_ATYPE()* and *PB_ATYPE_CALLBACK*. + +**Error indications:** Compiler error: *PB_HTYPE_ARRAY* or *PB_HTYPE_CALLBACK* +undeclared. + +Nanopb-0.1.6 (2012-09-02) +========================= + +Refactored field decoder interface +---------------------------------- +**Rationale:** Similarly to field encoders in nanopb-0.1.3. + +**Changes:** New functions with names *pb_decode_\** were added. + +**Required actions:** By defining NANOPB_INTERNALS, you can still keep using +the old functions. Recommended action is to replace any calls with the newer +*pb_decode_\** equivalents. + +**Error indications:** Compiler warning: implicit declaration of function +*pb_dec_string*, *pb_dec_varint*, *pb_dec_submessage* or similar. + +Nanopb-0.1.3 (2012-06-12) +========================= + +Refactored field encoder interface +---------------------------------- +**Rationale:** The old *pb_enc_\** functions were designed mostly for the +internal use by the core. Because they are internally accessed through +function pointers, their signatures had to be common. This led to a confusing +interface for external users. + +**Changes:** New functions with names *pb_encode_\** were added. These have +easier to use interfaces. The old functions are now only thin wrappers for +the new interface. + +**Required actions:** By defining NANOPB_INTERNALS, you can still keep using +the old functions. Recommended action is to replace any calls with the newer +*pb_encode_\** equivalents. + +**Error indications:** Compiler warning: implicit declaration of function +*pb_enc_string*, *pb_enc_varint, *pb_enc_submessage* or similar. + |