mirror of
https://github.com/espressif/openthread.git
synced 2026-06-06 05:24:51 +00:00
Robert Quattlebaum
b98e3c70eb
The data packing format that I designed for Spinel was a bit too clever for its own good. While elegant from a certain perspective, the behavior of the data blob (`D`), array (`A(...)`), and structure (`T(...)`) types was way too confusing. I thought that I was (as the guy who came up with it) immune from such confusion, but after taking the time to go through all the code and address all of the mishaps in the code it seems that the subtleties befuddled even its creator on a time or two. The specific issue that made me realize I needed to prioritize making this fix was #1393. As far as packing types go, this commit makes the following changes: * **New type `DATATYPE_DATA_WLEN` (`d`)**: Just like `DATATYPE_DATA` except that it ALWAYS prepends the length, irrespective of the type's location in the type string. Think of WLEN as being "With LENgth". Unless you are adding a property that has a type which is just a single data blob, you should use this type instead of `DATATYPE_DATA` (`D`). `DATATYPE_DATA` is still useful, so it will be sticking around. * **Changed type `DATATYPE_STRUCT` (was `T`, now `t`)**: The new struct type, ALWAYS prepends the length of the contents of the struct, just like `DATATYPE_DATA_WLEN`. The old `T` style struct still works and behaves the same way, but its use is now deprecated. * **Changed type `DATATYPE_ARRAY` (`A`)**: This type has changed in documentation only, as no one is currently using it in the way that it was originally specified. The change is that this type NEVER prepends the length of the entire array, and using it alongside other types is now unspecified (it should only be used alone). I also added some convenient macros for building up datatype signature strings that include structs. One of the goals of these changes was to make this commit a change in specification only, not to change what was currently on-the-wire. However, after updating the spec and then going through and updating all of the code to use the new nomenclature, I was horrified to find that, due to the confusing nature of the previous datatype signature string format, many properties that are arrays were not implemented correctly --- making them impossible to update or add fields to without breaking backward compatibility. To add insult to injury, some of these instances were written by me! This change updates all of the array properties to reflect how they should have been implemented to begin with.