diff options
| -rw-r--r-- | docs/concepts.rst | 16 | ||||
| -rw-r--r-- | docs/index.rst | 18 | ||||
| -rw-r--r-- | docs/reference.rst | 36 |
3 files changed, 35 insertions, 35 deletions
diff --git a/docs/concepts.rst b/docs/concepts.rst index b18c5057..052edcc1 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -255,16 +255,8 @@ For example this submessage in the Person.proto file:: generates this field description array for the structure *Person_PhoneNumber*:: const pb_field_t Person_PhoneNumber_fields[3] = { - {1, PB_HTYPE_REQUIRED | PB_LTYPE_STRING, - offsetof(Person_PhoneNumber, number), 0, - pb_membersize(Person_PhoneNumber, number), 0, 0}, - - {2, PB_HTYPE_OPTIONAL | PB_LTYPE_VARINT, - pb_delta(Person_PhoneNumber, type, number), - pb_delta(Person_PhoneNumber, has_type, type), - pb_membersize(Person_PhoneNumber, type), 0, - &Person_PhoneNumber_type_default}, - + PB_FIELD( 1, STRING , REQUIRED, STATIC, Person_PhoneNumber, number, number, 0), + PB_FIELD( 2, ENUM , OPTIONAL, STATIC, Person_PhoneNumber, type, number, &Person_PhoneNumber_type_default), PB_LAST_FIELD }; @@ -276,8 +268,8 @@ Most functions in nanopb return bool: *true* means success, *false* means failur The error messages help in guessing what is the underlying cause of the error. The most common error conditions are: -1) Running out of memory. Because everything is allocated from the stack, nanopb can't detect this itself. Encoding or decoding the same type of a message always takes the same amount of stack space. Therefore, if it works once, it works always. -2) Invalid field description. These are usually stored as constants, so if it works under the debugger, it always does. +1) Running out of memory, i.e. stack overflow. +2) Invalid field descriptors (would usually mean a bug in the generator). 3) IO errors in your own stream callbacks. 4) Errors that happen in your callback functions. 5) Exceeding the max_size or bytes_left of a stream. diff --git a/docs/index.rst b/docs/index.rst index 31d781ea..897f5529 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,23 +36,26 @@ Features and limitations **Features** #) Pure C runtime -#) Small code size (2–10 kB depending on processor) -#) Small ram usage (typically 200 bytes) +#) Small code size (2–10 kB depending on processor, plus any message definitions) +#) Small ram usage (typically ~300 bytes, plus any message structs) #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically. #) No malloc needed: everything can be allocated statically or on the stack. #) You can use either encoder or decoder alone to cut the code size in half. +#) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, packed arrays. +#) Callback mechanism for handling messages larger than can fit in available RAM. +#) Extensive set of tests. **Limitations** #) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module. -#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits. +#) Some speed has been sacrificed for code size. #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient. #) The deprecated Protocol Buffers feature called "groups" is not supported. #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file. #) Unknown fields are not preserved when decoding and re-encoding a message. #) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string. #) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format. -#) Cyclic references between messages are not supported. They could be supported in callback-mode if there was an option in the generator to set the mode. +#) Cyclic references between messages are supported only in callback mode. Getting started =============== @@ -104,10 +107,3 @@ Debugging and testing ===================== Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests. -This also generates a file called *breakpoints* which includes all lines returning *false* in nanopb. You can use this in gdb by typing *source breakpoints*, after which gdb will break on first nanopb error. - -Wishlist -======== -#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand. -#) A cleaner rewrite of the Python-based source generator. -#) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible. diff --git a/docs/reference.rst b/docs/reference.rst index fee1b702..93aae8b0 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -37,22 +37,23 @@ pb_type_t --------- Defines the encoder/decoder behaviour that should be used for a field. :: - typedef enum { ... } pb_type_t; + typedef uint8_t pb_type_t; -The low-order byte of the enumeration values defines the function that can be used for encoding and decoding the field data: +The low-order nibble of the enumeration values defines the function that can be used for encoding and decoding the field data: ==================== ===== ================================================ LTYPE identifier Value Storage format ==================== ===== ================================================ PB_LTYPE_VARINT 0x00 Integer. PB_LTYPE_SVARINT 0x01 Integer, zigzag encoded. -PB_LTYPE_FIXED 0x02 Integer or floating point. -PB_LTYPE_BYTES 0x03 Structure with *size_t* field and byte array. -PB_LTYPE_STRING 0x04 Null-terminated string. -PB_LTYPE_SUBMESSAGE 0x05 Submessage structure. +PB_LTYPE_FIXED32 0x02 32-bit integer or floating point. +PB_LTYPE_FIXED64 0x03 64-bit integer or floating point. +PB_LTYPE_BYTES 0x04 Structure with *size_t* field and byte array. +PB_LTYPE_STRING 0x05 Null-terminated string. +PB_LTYPE_SUBMESSAGE 0x06 Submessage structure. ==================== ===== ================================================ -The high-order byte defines whether the field is required, optional, repeated or callback: +The bits 4-5 define whether the field is required, optional or repeated: ==================== ===== ================================================ HTYPE identifier Value Field handling @@ -60,13 +61,24 @@ HTYPE identifier Value Field handling PB_HTYPE_REQUIRED 0x00 Verify that field exists in decoded message. PB_HTYPE_OPTIONAL 0x10 Use separate *has_<field>* boolean to specify whether the field is present. -PB_HTYPE_ARRAY 0x20 A repeated field with preallocated array. + (Unless it is a callback) +PB_HTYPE_REPEATED 0x20 A repeated field with preallocated array. Separate *<field>_count* for number of items. -PB_HTYPE_CALLBACK 0x30 A field with dynamic storage size, data is - actually a pointer to a structure containing a - callback function. + (Unless it is a callback) ==================== ===== ================================================ +The bits 6-7 define the how the storage for the field is allocated: + +==================== ===== ================================================ +ATYPE identifier Value Allocation method +==================== ===== ================================================ +PB_ATYPE_STATIC 0x00 Statically allocated storage in the structure. +PB_ATYPE_CALLBACK 0x40 A field with dynamic storage size. Struct field + actually contains a pointer to a callback + function. +==================== ===== ================================================ + + pb_field_t ---------- Describes a single structure field with memory position in relation to others. The descriptions are usually autogenerated. :: @@ -83,7 +95,7 @@ Describes a single structure field with memory position in relation to others. T } pb_packed; :tag: Tag number of the field or 0 to terminate a list of fields. -:type: LTYPE and HTYPE of the field. +:type: LTYPE, HTYPE and ATYPE of the field. :data_offset: Offset of field data, relative to the end of the previous field. :size_offset: Offset of *bool* flag for optional fields or *size_t* count for arrays, relative to field data. :data_size: Size of a single data entry, in bytes. For PB_LTYPE_BYTES, the size of the byte array inside the containing structure. For PB_HTYPE_CALLBACK, size of the C data type if known. |