.. contents ::
+
+
+
Compilation options
===================
-The following options can be specified using -D switch given to the C compiler:
-
-============================ ================================================================================================
-__BIG_ENDIAN__ Set this if your platform stores integers and floats in big-endian format.
- Mixed-endian systems (different layout for ints and floats) are currently not supported.
-NANOPB_INTERNALS Set this to expose the field encoder functions that are hidden since nanopb-0.1.3.
-PB_MAX_REQUIRED_FIELDS Maximum number of required fields to check for presence. Default value is 64. Increases stack
- usage 1 byte per every 8 fields. Compiler warning will tell if you need this.
-PB_FIELD_16BIT Add support for tag numbers > 255 and fields larger than 255 bytes or 255 array entries.
- Increases code size 3 bytes per each field. Compiler error will tell if you need this.
-PB_FIELD_32BIT Add support for tag numbers > 65535 and fields larger than 65535 bytes or 65535 array entries.
- Increases code size 9 bytes per each field. Compiler error will tell if you need this.
-PB_NO_ERRMSG Disables the support for error messages; only error information is the true/false return value.
- Decreases the code size by a few hundred bytes.
-PB_BUFFER_ONLY Disables the support for custom streams. Only supports encoding to memory buffers.
- Speeds up execution and decreases code size slightly.
-============================ ================================================================================================
-
-The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow raising some datatype limits to suit larger messages.
-Their need is recognized automatically by C-preprocessor #if-directives in the generated .pb.h files. The default setting is to use
-the smallest datatypes (least resources used).
+The following options can be specified using -D switch given to the C compiler
+when compiling the nanopb library and applications using it. You must have the
+same settings for the nanopb library and all code that includes pb.h.
+
+============================ ================================================
+__BIG_ENDIAN__ Set this if your platform stores integers and
+ floats in big-endian format. Mixed-endian
+ systems (different layout for ints and floats)
+ are currently not supported.
+NANOPB_INTERNALS Set this to expose the field encoder functions
+ that are hidden since nanopb-0.1.3.
+PB_MAX_REQUIRED_FIELDS Maximum number of required fields to check for
+ presence. Default value is 64. Increases stack
+ usage 1 byte per every 8 fields. Compiler
+ warning will tell if you need this.
+PB_FIELD_16BIT Add support for tag numbers > 255 and fields
+ larger than 255 bytes or 255 array entries.
+ Increases code size 3 bytes per each field.
+ Compiler error will tell if you need this.
+PB_FIELD_32BIT Add support for tag numbers > 65535 and fields
+ larger than 65535 bytes or 65535 array entries.
+ Increases code size 9 bytes per each field.
+ Compiler error will tell if you need this.
+PB_NO_ERRMSG Disables the support for error messages; only
+ error information is the true/false return
+ value. Decreases the code size by a few hundred
+ bytes.
+PB_BUFFER_ONLY Disables the support for custom streams. Only
+ supports encoding and decoding with memory
+ buffers. Speeds up execution and decreases code
+ size slightly.
+PB_OLD_CALLBACK_STYLE Use the old function signature (void\* instead
+ of void\*\*) for callback fields. This was the
+ default until nanopb-0.2.1.
+============================ ================================================
+
+The PB_MAX_REQUIRED_FIELDS, PB_FIELD_16BIT and PB_FIELD_32BIT settings allow
+raising some datatype limits to suit larger messages. Their need is recognized
+automatically by C-preprocessor #if-directives in the generated .pb.h files.
+The default setting is to use the smallest datatypes (least resources used).
+
+
+
+
+Proto file options
+==================
+The generator behaviour can be adjusted using these options, defined in the
+'nanopb.proto' file in the generator folder:
+
+============================ ================================================
+max_size Allocated size for 'bytes' and 'string' fields.
+max_count Allocated number of entries in arrays
+ ('repeated' fields).
+type Type of the generated field. Default value
+ is FT_DEFAULT, which selects automatically.
+ You can use FT_CALLBACK, FT_STATIC or FT_IGNORE
+ to force a callback field, a static field or
+ to completely ignore the field.
+long_names Prefix the enum name to the enum value in
+ definitions, i.e. 'EnumName_EnumValue'. Enabled
+ by default.
+packed_struct Make the generated structures packed.
+ NOTE: This cannot be used on CPUs that break
+ on unaligned accesses to variables.
+============================ ================================================
+
+These options can be defined for the .proto files before they are converted
+using the nanopb-generatory.py. There are three ways to define the options:
+
+1. Using a separate .options file.
+ This is the preferred way as of nanopb-0.2.1, because it has the best
+ compatibility with other protobuf libraries.
+2. Defining the options on the command line of nanopb_generator.py.
+ This only makes sense for settings that apply to a whole file.
+3. Defining the options in the .proto file using the nanopb extensions.
+ This is the way used in nanopb-0.1, and will remain supported in the
+ future. It however sometimes causes trouble when using the .proto file
+ with other protobuf libraries.
+
+The effect of the options is the same no matter how they are given. The most
+common purpose is to define maximum size for string fields in order to
+statically allocate them.
+
+Defining the options in a .options file
+---------------------------------------
+The preferred way to define options is to have a separate file
+'myproto.options' in the same directory as the 'myproto.proto'. The
+generator will automatically search for this file and read the options from
+it. The file format is as follows:
+
+* Lines starting with '#' or '//' are regarded as comments.
+* Blank lines are ignored.
+* All other lines should start with a field name pattern, followed by one or
+ more options. For example: *"MyMessage.myfield max_size:5 max_count:10"*.
+* The field name pattern is matched against a string of form 'Message.field'.
+ For nested messages, the string is 'Message.SubMessage.field'.
+* The field name pattern may use the notation recognized by Python fnmatch():
+ - \* matches any part of string, like 'Message.\*' for all fields
+ - \? matches any single character
+ - [seq] matches any of characters 's', 'e' and 'q'
+ - [!seq] matches any other character
+* The options are written as 'option_name:option_value' and several options
+ can be defined on same line, separated by whitespace.
+* Options defined later in the file override the ones specified earlier, so
+ it makes sense to define wildcard options first in the file and more specific
+ ones later.
+
+If preferred, the name of the options file can be set using the command line
+switch '-f' to nanopb_generator.py.
+
+Defining the options on command line
+------------------------------------
+The nanopb_generator.py has a simple command line option '-s OPTION:VALUE'.
+The setting applies to the whole file that is being processed.
+
+Defining the options in the .proto file
+---------------------------------------
+The .proto file format allows defining custom options for the fields.
+The nanopb library comes with 'nanopb.proto' which does exactly that, allowing
+you do define the options directly in the .proto file:
+
+ import "nanopb.proto";
+ required string name = 1 [(nanopb).max_size = 40];
+ repeated PhoneNumber phone = 4 [(nanopb).max_count = 5];
+
+A small complication is that you have to set the include path of protoc so that
+nanopb.proto can be found. This file, in turn, requires the file
+*google/protobuf/descriptor.proto*. This is usually installed under
+*/usr/include*. Therefore, to compile a .proto file which uses options, use a
+protoc command similar to::
+
+ protoc -I/usr/include -Inanopb/generator -I. -omessage.pb message.proto
+
+The options can be defined in file, message and field scopes::
+
+ option (nanopb_fileopt).max_size = 20; // File scope
+ message Message
+ {
+ option (nanopb_msgopt).max_size = 30; // Message scope
+ required string fieldsize = 1 [(nanopb).max_size = 40]; // Field scope
+ }
+
+
+
+
+
+
+
+
pb.h
====
---------
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
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
----------
} 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.
typedef struct _pb_callback_t pb_callback_t;
struct _pb_callback_t {
union {
- bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void *arg);
- bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, const void *arg);
+ bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void **arg);
+ bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, void * const *arg);
} funcs;
void *arg;
};
-The *arg* is passed to the callback when calling. It can be used to store any information that the callback might need.
+A pointer to the *arg* is passed to the callback when calling. It can be used to store any information that the callback might need.
+
+Previously the function received just the value of *arg* instead of a pointer to it. This old behaviour can be enabled by defining *PB_OLD_CALLBACK_STYLE*.
When calling `pb_encode`_, *funcs.encode* is used, and similarly when calling `pb_decode`_, *funcs.decode* is used. The function pointers are stored in the same memory location but are of incompatible types. You can set the function pointer to NULL to skip the field.
PB_WT_32BIT = 5
} pb_wire_type_t;
+
+
+
+
+
+
+
+
+
+
pb_encode.h
===========
If the submessage contains callback fields, the callback function might misbehave and write out a different amount of data on the second call. This situation is recognized and *false* is returned, but garbage will be written to the output before the problem is detected.
+
+
+
+
+
+
+
+
+
+
+
pb_decode.h
===========
Code Review / apps / agl-service-can-low-level.git / blobdiff