rik/nanopb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Petteri Aimonen
2013-03-02 16:27:31 +02:00
parent 0e3053894f
commit f8a143fdfe
3 changed files with 35 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/concepts.rst
View File

@@ -255,16 +255,8 @@ For example this submessage in the Person.proto file::
generates this field description array for the structure *Person_PhoneNumber*:: generates this field description array for the structure *Person_PhoneNumber*::
const pb_field_t Person_PhoneNumber_fields[3] = { const pb_field_t Person_PhoneNumber_fields[3] = {
{1, PB_HTYPE_REQUIRED | PB_LTYPE_STRING, PB_FIELD( 1, STRING , REQUIRED, STATIC, Person_PhoneNumber, number, number, 0),
offsetof(Person_PhoneNumber, number), 0, PB_FIELD( 2, ENUM , OPTIONAL, STATIC, Person_PhoneNumber, type, number, &Person_PhoneNumber_type_default),
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_LAST_FIELD 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: 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. 1) Running out of memory, i.e. stack overflow.
2) Invalid field description. These are usually stored as constants, so if it works under the debugger, it always does. 2) Invalid field descriptors (would usually mean a bug in the generator).
3) IO errors in your own stream callbacks. 3) IO errors in your own stream callbacks.
4) Errors that happen in your callback functions. 4) Errors that happen in your callback functions.
5) Exceeding the max_size or bytes_left of a stream. 5) Exceeding the max_size or bytes_left of a stream.

18
docs/index.rst
View File

@@ -36,23 +36,26 @@ Features and limitations
**Features** **Features**
#) Pure C runtime #) Pure C runtime
#) Small code size (2–10 kB depending on processor) #) Small code size (2–10 kB depending on processor, plus any message definitions)
#) Small ram usage (typically 200 bytes) #) 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. #) 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. #) 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. #) 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** **Limitations**
#) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module. #) 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. #) 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. #) 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. #) 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. #) 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. #) 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. #) 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 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. 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.

36
docs/reference.rst
View File

@@ -37,22 +37,23 @@ pb_type_t
--------- ---------
Defines the encoder/decoder behaviour that should be used for a field. :: 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 LTYPE identifier Value Storage format
==================== ===== ================================================ ==================== ===== ================================================
PB_LTYPE_VARINT 0x00 Integer. PB_LTYPE_VARINT 0x00 Integer.
PB_LTYPE_SVARINT 0x01 Integer, zigzag encoded. PB_LTYPE_SVARINT 0x01 Integer, zigzag encoded.
PB_LTYPE_FIXED 0x02 Integer or floating point. PB_LTYPE_FIXED32 0x02 32-bit integer or floating point.
PB_LTYPE_BYTES 0x03 Structure with *size_t* field and byte array. PB_LTYPE_FIXED64 0x03 64-bit integer or floating point.
PB_LTYPE_STRING 0x04 Null-terminated string. PB_LTYPE_BYTES 0x04 Structure with *size_t* field and byte array.
PB_LTYPE_SUBMESSAGE 0x05 Submessage structure. 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 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_REQUIRED 0x00 Verify that field exists in decoded message.
PB_HTYPE_OPTIONAL 0x10 Use separate *has_<field>* boolean to specify PB_HTYPE_OPTIONAL 0x10 Use separate *has_<field>* boolean to specify
whether the field is present. 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. Separate *<field>_count* for number of items.
PB_HTYPE_CALLBACK 0x30 A field with dynamic storage size, data is (Unless it is a callback)
actually a pointer to a structure containing a
callback function.
==================== ===== ================================================ ==================== ===== ================================================
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 pb_field_t
---------- ----------
Describes a single structure field with memory position in relation to others. The descriptions are usually autogenerated. :: 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; } pb_packed;
:tag: Tag number of the field or 0 to terminate a list of fields. :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. :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. :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. :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.