From b9e1b4435a406a8a27c078ea05dee1240e51704a Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Tue, 2 May 2017 18:29:37 +0200 Subject: Added external libraries from openXC CMake files. Now libraries are cleanly included and built. Change-Id: Iaa85639578b55b2da8357bc438426403e2cca8de Signed-off-by: Romain Forlot --- CAN-binder/libs/nanopb/docs/Makefile | 9 - CAN-binder/libs/nanopb/docs/concepts.rst | 392 ---- CAN-binder/libs/nanopb/docs/generator_flow.svg | 2869 ------------------------ CAN-binder/libs/nanopb/docs/index.rst | 127 -- CAN-binder/libs/nanopb/docs/logo/logo.png | Bin 14973 -> 0 bytes CAN-binder/libs/nanopb/docs/logo/logo.svg | 1470 ------------ CAN-binder/libs/nanopb/docs/logo/logo16px.png | Bin 854 -> 0 bytes CAN-binder/libs/nanopb/docs/logo/logo48px.png | Bin 2577 -> 0 bytes CAN-binder/libs/nanopb/docs/lsr.css | 240 -- CAN-binder/libs/nanopb/docs/menu.rst | 13 - CAN-binder/libs/nanopb/docs/migration.rst | 289 --- CAN-binder/libs/nanopb/docs/reference.rst | 770 ------- CAN-binder/libs/nanopb/docs/security.rst | 84 - 13 files changed, 6263 deletions(-) delete mode 100644 CAN-binder/libs/nanopb/docs/Makefile delete mode 100644 CAN-binder/libs/nanopb/docs/concepts.rst delete mode 100644 CAN-binder/libs/nanopb/docs/generator_flow.svg delete mode 100644 CAN-binder/libs/nanopb/docs/index.rst delete mode 100644 CAN-binder/libs/nanopb/docs/logo/logo.png delete mode 100644 CAN-binder/libs/nanopb/docs/logo/logo.svg delete mode 100644 CAN-binder/libs/nanopb/docs/logo/logo16px.png delete mode 100644 CAN-binder/libs/nanopb/docs/logo/logo48px.png delete mode 100644 CAN-binder/libs/nanopb/docs/lsr.css delete mode 100644 CAN-binder/libs/nanopb/docs/menu.rst delete mode 100644 CAN-binder/libs/nanopb/docs/migration.rst delete mode 100644 CAN-binder/libs/nanopb/docs/reference.rst delete mode 100644 CAN-binder/libs/nanopb/docs/security.rst (limited to 'CAN-binder/libs/nanopb/docs') diff --git a/CAN-binder/libs/nanopb/docs/Makefile b/CAN-binder/libs/nanopb/docs/Makefile deleted file mode 100644 index 0dbd97cf..00000000 --- a/CAN-binder/libs/nanopb/docs/Makefile +++ /dev/null @@ -1,9 +0,0 @@ -all: index.html concepts.html reference.html security.html migration.html \ - generator_flow.png - -%.png: %.svg - rsvg $< $@ - -%.html: %.rst - rst2html --stylesheet=lsr.css --link-stylesheet $< $@ - sed -i 's!!\n!' $@ diff --git a/CAN-binder/libs/nanopb/docs/concepts.rst b/CAN-binder/libs/nanopb/docs/concepts.rst deleted file mode 100644 index 2e0d3f9b..00000000 --- a/CAN-binder/libs/nanopb/docs/concepts.rst +++ /dev/null @@ -1,392 +0,0 @@ -====================== -Nanopb: Basic concepts -====================== - -.. include :: menu.rst - -The things outlined here are the underlying concepts of the nanopb design. - -.. contents:: - -Proto files -=========== -All Protocol Buffers implementations use .proto files to describe the message -format. The point of these files is to be a portable interface description -language. - -Compiling .proto files for nanopb ---------------------------------- -Nanopb uses the Google's protoc compiler to parse the .proto file, and then a -python script to generate the C header and source code from it:: - - user@host:~$ protoc -omessage.pb message.proto - user@host:~$ python ../generator/nanopb_generator.py message.pb - Writing to message.h and message.c - user@host:~$ - -Modifying generator behaviour ------------------------------ -Using generator options, you can set maximum sizes for fields in order to -allocate them statically. The preferred way to do this is to create an .options -file with the same name as your .proto file:: - - # Foo.proto - message Foo { - required string name = 1; - } - -:: - - # Foo.options - Foo.name max_size:16 - -For more information on this, see the `Proto file options`_ section in the -reference manual. - -.. _`Proto file options`: reference.html#proto-file-options - -Streams -======= - -Nanopb uses streams for accessing the data in encoded format. -The stream abstraction is very lightweight, and consists of a structure (*pb_ostream_t* or *pb_istream_t*) which contains a pointer to a callback function. - -There are a few generic rules for callback functions: - -#) Return false on IO errors. The encoding or decoding process will abort immediately. -#) Use state to store your own data, such as a file descriptor. -#) *bytes_written* and *bytes_left* are updated by pb_write and pb_read. -#) Your callback may be used with substreams. In this case *bytes_left*, *bytes_written* and *max_size* have smaller values than the original stream. Don't use these values to calculate pointers. -#) Always read or write the full requested length of data. For example, POSIX *recv()* needs the *MSG_WAITALL* parameter to accomplish this. - -Output streams --------------- - -:: - - struct _pb_ostream_t - { - bool (*callback)(pb_ostream_t *stream, const uint8_t *buf, size_t count); - void *state; - size_t max_size; - size_t bytes_written; - }; - -The *callback* for output stream may be NULL, in which case the stream simply counts the number of bytes written. In this case, *max_size* is ignored. - -Otherwise, if *bytes_written* + bytes_to_be_written is larger than *max_size*, pb_write returns false before doing anything else. If you don't want to limit the size of the stream, pass SIZE_MAX. - -**Example 1:** - -This is the way to get the size of the message without storing it anywhere:: - - Person myperson = ...; - pb_ostream_t sizestream = {0}; - pb_encode(&sizestream, Person_fields, &myperson); - printf("Encoded size is %d\n", sizestream.bytes_written); - -**Example 2:** - -Writing to stdout:: - - bool callback(pb_ostream_t *stream, const uint8_t *buf, size_t count) - { - FILE *file = (FILE*) stream->state; - return fwrite(buf, 1, count, file) == count; - } - - pb_ostream_t stdoutstream = {&callback, stdout, SIZE_MAX, 0}; - -Input streams -------------- -For input streams, there is one extra rule: - -#) You don't need to know the length of the message in advance. After getting EOF error when reading, set bytes_left to 0 and return false. Pb_decode will detect this and if the EOF was in a proper position, it will return true. - -Here is the structure:: - - struct _pb_istream_t - { - bool (*callback)(pb_istream_t *stream, uint8_t *buf, size_t count); - void *state; - size_t bytes_left; - }; - -The *callback* must always be a function pointer. *Bytes_left* is an upper limit on the number of bytes that will be read. You can use SIZE_MAX if your callback handles EOF as described above. - -**Example:** - -This function binds an input stream to stdin: - -:: - - bool callback(pb_istream_t *stream, uint8_t *buf, size_t count) - { - FILE *file = (FILE*)stream->state; - bool status; - - if (buf == NULL) - { - while (count-- && fgetc(file) != EOF); - return count == 0; - } - - status = (fread(buf, 1, count, file) == count); - - if (feof(file)) - stream->bytes_left = 0; - - return status; - } - - pb_istream_t stdinstream = {&callback, stdin, SIZE_MAX}; - -Data types -========== - -Most Protocol Buffers datatypes have directly corresponding C datatypes, such as int32 is int32_t, float is float and bool is bool. However, the variable-length datatypes are more complex: - -1) Strings, bytes and repeated fields of any type map to callback functions by default. -2) If there is a special option *(nanopb).max_size* specified in the .proto file, string maps to null-terminated char array and bytes map to a structure containing a char array and a size field. -3) If *(nanopb).fixed_length* is set to *true* and *(nanopb).max_size* is also set, then bytes map to an inline byte array of fixed size. -4) If there is a special option *(nanopb).max_count* specified on a repeated field, it maps to an array of whatever type is being repeated. Another field will be created for the actual number of entries stored. - -=============================================================================== ======================= - field in .proto autogenerated in .h -=============================================================================== ======================= -required string name = 1; pb_callback_t name; -required string name = 1 [(nanopb).max_size = 40]; char name[40]; -repeated string name = 1 [(nanopb).max_size = 40]; pb_callback_t name; -repeated string name = 1 [(nanopb).max_size = 40, (nanopb).max_count = 5]; | size_t name_count; - | char name[5][40]; -required bytes data = 1 [(nanopb).max_size = 40]; | typedef struct { - | size_t size; - | pb_byte_t bytes[40]; - | } Person_data_t; - | Person_data_t data; -required bytes data = 1 [(nanopb).max_size = 40, (nanopb).fixed_length = true]; | pb_byte_t data[40]; -=============================================================================== ======================= - -The maximum lengths are checked in runtime. If string/bytes/array exceeds the allocated length, *pb_decode* will return false. - -Note: for the *bytes* datatype, the field length checking may not be exact. -The compiler may add some padding to the *pb_bytes_t* structure, and the nanopb runtime doesn't know how much of the structure size is padding. Therefore it uses the whole length of the structure for storing data, which is not very smart but shouldn't cause problems. In practise, this means that if you specify *(nanopb).max_size=5* on a *bytes* field, you may be able to store 6 bytes there. For the *string* field type, the length limit is exact. - -Field callbacks -=============== -When a field has dynamic length, nanopb cannot statically allocate storage for it. Instead, it allows you to handle the field in whatever way you want, using a callback function. - -The `pb_callback_t`_ structure contains a function pointer and a *void* pointer called *arg* you can use for passing data to the callback. If the function pointer is NULL, the field will be skipped. A pointer to the *arg* is passed to the function, so that it can modify it and retrieve the value. - -The actual behavior of the callback function is different in encoding and decoding modes. In encoding mode, the callback is called once and should write out everything, including field tags. In decoding mode, the callback is called repeatedly for every data item. - -.. _`pb_callback_t`: reference.html#pb-callback-t - -Encoding callbacks ------------------- -:: - - bool (*encode)(pb_ostream_t *stream, const pb_field_t *field, void * const *arg); - -When encoding, the callback should write out complete fields, including the wire type and field number tag. It can write as many or as few fields as it likes. For example, if you want to write out an array as *repeated* field, you should do it all in a single call. - -Usually you can use `pb_encode_tag_for_field`_ to encode the wire type and tag number of the field. However, if you want to encode a repeated field as a packed array, you must call `pb_encode_tag`_ instead to specify a wire type of *PB_WT_STRING*. - -If the callback is used in a submessage, it will be called multiple times during a single call to `pb_encode`_. In this case, it must produce the same amount of data every time. If the callback is directly in the main message, it is called only once. - -.. _`pb_encode`: reference.html#pb-encode -.. _`pb_encode_tag_for_field`: reference.html#pb-encode-tag-for-field -.. _`pb_encode_tag`: reference.html#pb-encode-tag - -This callback writes out a dynamically sized string:: - - bool write_string(pb_ostream_t *stream, const pb_field_t *field, void * const *arg) - { - char *str = get_string_from_somewhere(); - if (!pb_encode_tag_for_field(stream, field)) - return false; - - return pb_encode_string(stream, (uint8_t*)str, strlen(str)); - } - -Decoding callbacks ------------------- -:: - - bool (*decode)(pb_istream_t *stream, const pb_field_t *field, void **arg); - -When decoding, the callback receives a length-limited substring that reads the contents of a single field. The field tag has already been read. For *string* and *bytes*, the length value has already been parsed, and is available at *stream->bytes_left*. - -The callback will be called multiple times for repeated fields. For packed fields, you can either read multiple values until the stream ends, or leave it to `pb_decode`_ to call your function over and over until all values have been read. - -.. _`pb_decode`: reference.html#pb-decode - -This callback reads multiple integers and prints them:: - - bool read_ints(pb_istream_t *stream, const pb_field_t *field, void **arg) - { - while (stream->bytes_left) - { - uint64_t value; - if (!pb_decode_varint(stream, &value)) - return false; - printf("%lld\n", value); - } - return true; - } - -Field description array -======================= - -For using the *pb_encode* and *pb_decode* functions, you need an array of pb_field_t constants describing the structure you wish to encode. This description is usually autogenerated from .proto file. - -For example this submessage in the Person.proto file:: - - message Person { - message PhoneNumber { - required string number = 1 [(nanopb).max_size = 40]; - optional PhoneType type = 2 [default = HOME]; - } - } - -generates this field description array for the structure *Person_PhoneNumber*:: - - const pb_field_t Person_PhoneNumber_fields[3] = { - 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 - }; - -Oneof -===== -Protocol Buffers supports `oneof`_ sections. Here is an example of ``oneof`` usage:: - - message MsgType1 { - required int32 value = 1; - } - - message MsgType2 { - required bool value = 1; - } - - message MsgType3 { - required int32 value1 = 1; - required int32 value2 = 2; - } - - message MyMessage { - required uint32 uid = 1; - required uint32 pid = 2; - required uint32 utime = 3; - - oneof payload { - MsgType1 msg1 = 4; - MsgType2 msg2 = 5; - MsgType3 msg3 = 6; - } - } - -Nanopb will generate ``payload`` as a C union and add an additional field ``which_payload``:: - - typedef struct _MyMessage { - uint32_t uid; - uint32_t pid; - uint32_t utime; - pb_size_t which_payload; - union { - MsgType1 msg1; - MsgType2 msg2; - MsgType3 msg3; - } payload; - /* @@protoc_insertion_point(struct:MyMessage) */ - } MyMessage; - -``which_payload`` indicates which of the ``oneof`` fields is actually set. -The user is expected to set the filed manually using the correct field tag:: - - MyMessage msg = MyMessage_init_zero; - msg.payload.msg2.value = true; - msg.which_payload = MyMessage_msg2_tag; - -Notice that neither ``which_payload`` field nor the unused fileds in ``payload`` -will consume any space in the resulting encoded message. - -.. _`oneof`: https://developers.google.com/protocol-buffers/docs/reference/proto2-spec#oneof_and_oneof_field - -Extension fields -================ -Protocol Buffers supports a concept of `extension fields`_, which are -additional fields to a message, but defined outside the actual message. -The definition can even be in a completely separate .proto file. - -The base message is declared as extensible by keyword *extensions* in -the .proto file:: - - message MyMessage { - .. fields .. - extensions 100 to 199; - } - -For each extensible message, *nanopb_generator.py* declares an additional -callback field called *extensions*. The field and associated datatype -*pb_extension_t* forms a linked list of handlers. When an unknown field is -encountered, the decoder calls each handler in turn until either one of them -handles the field, or the list is exhausted. - -The actual extensions are declared using the *extend* keyword in the .proto, -and are in the global namespace:: - - extend MyMessage { - optional int32 myextension = 100; - } - -For each extension, *nanopb_generator.py* creates a constant of type -*pb_extension_type_t*. To link together the base message and the extension, -you have to: - -1. Allocate storage for your field, matching the datatype in the .proto. - For example, for a *int32* field, you need a *int32_t* variable to store - the value. -2. Create a *pb_extension_t* constant, with pointers to your variable and - to the generated *pb_extension_type_t*. -3. Set the *message.extensions* pointer to point to the *pb_extension_t*. - -An example of this is available in *tests/test_encode_extensions.c* and -*tests/test_decode_extensions.c*. - -.. _`extension fields`: https://developers.google.com/protocol-buffers/docs/proto#extensions - -Message framing -=============== -Protocol Buffers does not specify a method of framing the messages for transmission. -This is something that must be provided by the library user, as there is no one-size-fits-all -solution. Typical needs for a framing format are to: - -1. Encode the message length. -2. Encode the message type. -3. Perform any synchronization and error checking that may be needed depending on application. - -For example UDP packets already fullfill all the requirements, and TCP streams typically only -need a way to identify the message length and type. Lower level interfaces such as serial ports -may need a more robust frame format, such as HDLC (high-level data link control). - -Nanopb provides a few helpers to facilitate implementing framing formats: - -1. Functions *pb_encode_delimited* and *pb_decode_delimited* prefix the message data with a varint-encoded length. -2. Union messages and oneofs are supported in order to implement top-level container messages. -3. Message IDs can be specified using the *(nanopb_msgopt).msgid* option and can then be accessed from the header. - -Return values and error handling -================================ - -Most functions in nanopb return bool: *true* means success, *false* means failure. There is also some support for error messages for debugging purposes: the error messages go in *stream->errmsg*. - -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, 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. -6) Exceeding the max_size of a string or array field -7) Invalid protocol buffers binary message. diff --git a/CAN-binder/libs/nanopb/docs/generator_flow.svg b/CAN-binder/libs/nanopb/docs/generator_flow.svg deleted file mode 100644 index e30277a7..00000000 --- a/CAN-binder/libs/nanopb/docs/generator_flow.svg +++ /dev/null @@ -1,2869 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MyMessage.proto - - - pb_encode( ); - pb_decode( ); - - - nanopb_generator.py - - - - - - - - - - - - - - - - - - MyMessage.pb.c - MyMessage.pb.h - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - c - - Nanopb library - - - - Protocol Buffersmessages - - - - - - - - - - - - - - - - - - - - - Data structures - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - User application - - - diff --git a/CAN-binder/libs/nanopb/docs/index.rst b/CAN-binder/libs/nanopb/docs/index.rst deleted file mode 100644 index afc7ee4f..00000000 --- a/CAN-binder/libs/nanopb/docs/index.rst +++ /dev/null @@ -1,127 +0,0 @@ -============================================= -Nanopb: Protocol Buffers with small code size -============================================= - -.. include :: menu.rst - -Nanopb is an ANSI-C library for encoding and decoding messages in Google's `Protocol Buffers`__ format with minimal requirements for RAM and code space. -It is primarily suitable for 32-bit microcontrollers. - -__ https://developers.google.com/protocol-buffers/docs/reference/overview - -Overall structure -================= - -For the runtime program, you always need *pb.h* for type declarations. -Depending on whether you want to encode, decode, or both, you also need *pb_encode.h/c* or *pb_decode.h/c*. - -The high-level encoding and decoding functions take an array of *pb_field_t* structures, which describes the fields of a message structure. Usually you want these autogenerated from a *.proto* file. The tool script *nanopb_generator.py* accomplishes this. - -.. image:: generator_flow.png - -So a typical project might include these files: - -1) Nanopb runtime library: - - pb.h - - pb_common.h and pb_common.c (always needed) - - pb_decode.h and pb_decode.c (needed for decoding messages) - - pb_encode.h and pb_encode.c (needed for encoding messages) -2) Protocol description (you can have many): - - person.proto (just an example) - - person.pb.c (autogenerated, contains initializers for const arrays) - - person.pb.h (autogenerated, contains type declarations) - -Features and limitations -======================== - -**Features** - -#) Pure C runtime -#) 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. Optional malloc support available. -#) 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, oneofs, packed arrays, extension fields. -#) Callback mechanism for handling messages larger than can fit in available RAM. -#) Extensive set of tests. - -**Limitations** - -#) 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. -#) Cyclic references between messages are supported only in callback and malloc mode. - -Getting started -=============== - -For starters, consider this simple message:: - - message Example { - required int32 value = 1; - } - -Save this in *message.proto* and compile it:: - - user@host:~$ protoc -omessage.pb message.proto - user@host:~$ python nanopb/generator/nanopb_generator.py message.pb - -You should now have in *message.pb.h*:: - - typedef struct { - int32_t value; - } Example; - - extern const pb_field_t Example_fields[2]; - -Now in your main program do this to encode a message:: - - Example mymessage = {42}; - uint8_t buffer[10]; - pb_ostream_t stream = pb_ostream_from_buffer(buffer, sizeof(buffer)); - pb_encode(&stream, Example_fields, &mymessage); - -After that, buffer will contain the encoded message. -The number of bytes in the message is stored in *stream.bytes_written*. -You can feed the message to *protoc --decode=Example message.proto* to verify its validity. - -For a complete example of the simple case, see *example/simple.c*. -For a more complex example with network interface, see the *example/network_server* subdirectory. - -Compiler requirements -===================== -Nanopb should compile with most ansi-C compatible compilers. It however -requires a few header files to be available: - -#) *string.h*, with these functions: *strlen*, *memcpy*, *memset* -#) *stdint.h*, for definitions of *int32_t* etc. -#) *stddef.h*, for definition of *size_t* -#) *stdbool.h*, for definition of *bool* - -If these header files do not come with your compiler, you can use the -file *extra/pb_syshdr.h* instead. It contains an example of how to provide -the dependencies. You may have to edit it a bit to suit your custom platform. - -To use the pb_syshdr.h, define *PB_SYSTEM_HEADER* as *"pb_syshdr.h"* (including the quotes). -Similarly, you can provide a custom include file, which should provide all the dependencies -listed above. - -Running the test cases -====================== -Extensive unittests and test cases are included under the *tests* folder. - -To build the tests, you will need the `scons`__ build system. The tests should -be runnable on most platforms. Windows and Linux builds are regularly tested. - -__ http://www.scons.org/ - -In addition to the build system, you will also need a working Google Protocol -Buffers *protoc* compiler, and the Python bindings for Protocol Buffers. On -Debian-based systems, install the following packages: *protobuf-compiler*, -*python-protobuf* and *libprotobuf-dev*. - diff --git a/CAN-binder/libs/nanopb/docs/logo/logo.png b/CAN-binder/libs/nanopb/docs/logo/logo.png deleted file mode 100644 index 0d9534fa..00000000 Binary files a/CAN-binder/libs/nanopb/docs/logo/logo.png and /dev/null differ diff --git a/CAN-binder/libs/nanopb/docs/logo/logo.svg b/CAN-binder/libs/nanopb/docs/logo/logo.svg deleted file mode 100644 index 91ab28b6..00000000 --- a/CAN-binder/libs/nanopb/docs/logo/logo.svg +++ /dev/null @@ -1,1470 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - Pb - Pb - - - - - - - - - - - - - - - - - - nano - nano - - - - - diff --git a/CAN-binder/libs/nanopb/docs/logo/logo16px.png b/CAN-binder/libs/nanopb/docs/logo/logo16px.png deleted file mode 100644 index 8db0e2ef..00000000 Binary files a/CAN-binder/libs/nanopb/docs/logo/logo16px.png and /dev/null differ diff --git a/CAN-binder/libs/nanopb/docs/logo/logo48px.png b/CAN-binder/libs/nanopb/docs/logo/logo48px.png deleted file mode 100644 index b598c011..00000000 Binary files a/CAN-binder/libs/nanopb/docs/logo/logo48px.png and /dev/null differ diff --git a/CAN-binder/libs/nanopb/docs/lsr.css b/CAN-binder/libs/nanopb/docs/lsr.css deleted file mode 100644 index 429bce51..00000000 --- a/CAN-binder/libs/nanopb/docs/lsr.css +++ /dev/null @@ -1,240 +0,0 @@ -/* -Author: Peter Parente -Date: 2008/01/22 -Version: 1.0 (modified) -Copyright: This stylesheet has been placed in the public domain - free to edit and use for all uses. -*/ - -body { - font: 100% sans-serif; - background: #ffffff; - color: black; - margin: 2em; - padding: 0em 2em; -} - -p.topic-title { - font-weight: bold; -} - -table.docinfo { - text-align: left; - margin: 2em 0em; -} - -a[href] { - color: #436976; - background-color: transparent; -} - -a.toc-backref { - text-decoration: none; -} - -h1 a[href] { - color: #003a6b; - text-decoration: none; - background-color: transparent; -} - -a.strong { - font-weight: bold; -} - -img { - margin: 0; - border: 0; -} - -p { - margin: 0.5em 0 1em 0; - line-height: 1.5em; -} - -p a:visited { - color: purple; - background-color: transparent; -} - -p a:active { - color: red; - background-color: transparent; -} - -a:hover { - text-decoration: none; -} - -p img { - border: 0; - margin: 0; -} - -p.rubric { - font-weight: bold; - font-style: italic; -} - -em { - font-style: normal; - font-family: monospace; - font-weight: bold; -} - -pre { - border-left: 3px double #aaa; - padding: 5px 10px; - background-color: #f6f6f6; -} - -h1.title { - color: #003a6b; - font-size: 180%; - margin-bottom: 0em; -} - -h2.subtitle { - color: #003a6b; - border-bottom: 0px; -} - -h1, h2, h3, h4, h5, h6 { - color: #555; - background-color: transparent; - margin: 0em; - padding-top: 0.5em; -} - -h1 { - font-size: 150%; - margin-bottom: 0.5em; - border-bottom: 2px solid #aaa; -} - -h2 { - font-size: 130%; - margin-bottom: 0.5em; - border-bottom: 1px solid #aaa; -} - -h3 { - font-size: 120%; - margin-bottom: 0.5em; -} - -h4 { - font-size: 110%; - font-weight: bold; - margin-bottom: 0.5em; -} - -h5 { - font-size: 105%; - font-weight: bold; - margin-bottom: 0.5em; -} - -h6 { - font-size: 100%; - font-weight: bold; - margin-bottom: 0.5em; -} - -dt { - font-style: italic; -} - -dd { - margin-bottom: 1.5em; -} - -div.admonition, div.note, div.tip, div.caution, div.important { - margin: 2em 2em; - padding: 0em 1em; - border-top: 1px solid #aaa; - border-left: 1px solid #aaa; - border-bottom: 2px solid #555; - border-right: 2px solid #555; -} - -div.important { - background: transparent url('../images/important.png') 10px 2px no-repeat; -} - -div.caution { - background: transparent url('../images/caution.png') 10px 2px no-repeat; -} - -div.note { - background: transparent url('../images/note.png') 10px 2px no-repeat; -} - -div.tip { - background: transparent url('../images/tip.png') 10px 2px no-repeat; -} - -div.admonition-example { - background: transparent url('../images/tip.png') 10px 2px no-repeat; -} - -div.admonition-critical-example { - background: transparent url('../images/important.png') 10px 2px no-repeat; -} - -p.admonition-title { - font-weight: bold; - border-bottom: 1px solid #aaa; - padding-left: 30px; -} - -table.docutils { - text-align: left; - border: 1px solid gray; - border-collapse: collapse; - margin: 1.5em 0em; -} - -table.docutils caption { - font-style: italic; -} - -table.docutils td, table.docutils th { - padding: 0.25em 0.5em; -} - -th.field-name { - text-align: right; - width: 15em; -} - -table.docutils th { - font-family: monospace; - background-color: #f6f6f6; - vertical-align: middle; -} - -table.field-list { - border: none; -} - -div.sidebar { - margin: 2em 2em 2em 0em; - padding: 0em 1em; - border-top: 1px solid #aaa; - border-left: 1px solid #aaa; - border-bottom: 2px solid #555; - border-right: 2px solid #555; -} - -p.sidebar-title { - margin-bottom: 0em; - color: #003a6b; - border-bottom: 1px solid #aaa; - font-weight: bold; -} - -p.sidebar-subtitle { - margin-top: 0em; - font-style: italic; - color: #003a6b; -} diff --git a/CAN-binder/libs/nanopb/docs/menu.rst b/CAN-binder/libs/nanopb/docs/menu.rst deleted file mode 100644 index 2c110def..00000000 --- a/CAN-binder/libs/nanopb/docs/menu.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. sidebar :: Documentation index - - 1) `Overview`_ - 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/CAN-binder/libs/nanopb/docs/migration.rst b/CAN-binder/libs/nanopb/docs/migration.rst deleted file mode 100644 index d6b32b53..00000000 --- a/CAN-binder/libs/nanopb/docs/migration.rst +++ /dev/null @@ -1,289 +0,0 @@ -===================================== -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.8 (2017-03-05) -========================= -Fully drain substreams before closing - -**Rationale:** If the substream functions were called directly and the caller -did not completely empty the substring before closing it, the parent stream -would be put into an incorrect state. - -**Changes:** *pb_close_string_substream* can now error and returns a boolean. - -**Required actions:** Add error checking onto any call to -*pb_close_string_substream*. - -Nanopb-0.3.5 (2016-02-13) -========================= - -Add support for platforms without uint8_t ------------------------------------------ -**Rationale:** Some platforms cannot access 8-bit sized values directly, and -do not define *uint8_t*. Nanopb previously didn't support these platforms. - -**Changes:** References to *uint8_t* were replaced with several alternatives, -one of them being a new *pb_byte_t* typedef. This in turn uses *uint_least8_t* -which means the smallest available type. - -**Required actions:** If your platform does not have a standards-compliant -*stdint.h*, it may lack the definition for *[u]int_least8_t*. This must be -added manually, example can be found in *extra/pb_syshdr.h*. - -**Error indications:** Compiler error: "unknown type name 'uint_least8_t'". - -Nanopb-0.3.2 (2015-01-24) -========================= - -Add support for OneOfs ----------------------- -**Rationale:** Previously nanopb did not support the *oneof* construct in -*.proto* files. Those fields were generated as regular *optional* fields. - -**Changes:** OneOfs are now generated as C unions. Callback fields are not -supported inside oneof and generator gives an error. - -**Required actions:** The generator option *no_unions* can be used to restore old -behaviour and to allow callbacks to be used. To use unions, one change is -needed: use *which_xxxx* field to detect which field is present, instead -of *has_xxxx*. Compare the value against *MyStruct_myfield_tag*. - -**Error indications:** Generator error: "Callback fields inside of oneof are -not supported". Compiler error: "Message" has no member named "has_xxxx". - -Nanopb-0.3.0 (2014-08-26) -========================= - -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. - -Change data type of field counts to pb_size_t ---------------------------------------------- -**Rationale:** Often nanopb is used with small arrays, such as 255 items or -less. Using a full *size_t* field to store the array count wastes memory if -there are many arrays. There already exists parameters *PB_FIELD_16BIT* and -*PB_FIELD_32BIT* which tell nanopb what is the maximum size of arrays in use. - -**Changes:** Generator will now use *pb_size_t* for the array *_count* fields. -The size of the type will be controlled by the *PB_FIELD_16BIT* and -*PB_FIELD_32BIT* compilation time options. - -**Required actions:** Regenerate all *.pb.h* files. In some cases casts to the -*pb_size_t* type may need to be added in the user code when accessing the -*_count* fields. - -**Error indications:** Incorrect data at runtime, crashes. But note that other -changes in the same version already require regenerating the files and have -better indications of errors, so this is only an issue for development -versions. - -Renamed some macros and identifiers ------------------------------------ -**Rationale:** Some names in nanopb core were badly chosen and conflicted with -ISO C99 reserved names or lacked a prefix. While they haven't caused trouble -so far, it is reasonable to switch to non-conflicting names as these are rarely -used from user code. - -**Changes:** The following identifier names have changed: - - * Macros: - - * STATIC_ASSERT(x) -> PB_STATIC_ASSERT(x) - * UNUSED(x) -> PB_UNUSED(x) - - * Include guards: - - * _PB_filename_ -> PB_filename_INCLUDED - - * Structure forward declaration tags: - - * _pb_field_t -> pb_field_s - * _pb_bytes_array_t -> pb_bytes_array_s - * _pb_callback_t -> pb_callback_s - * _pb_extension_type_t -> pb_extension_type_s - * _pb_extension_t -> pb_extension_s - * _pb_istream_t -> pb_istream_s - * _pb_ostream_t -> pb_ostream_s - -**Required actions:** Regenerate all *.pb.c* files. If you use any of the above -identifiers in your application code, perform search-replace to the new name. - -**Error indications:** Compiler errors on lines with the macro/type names. - -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. - diff --git a/CAN-binder/libs/nanopb/docs/reference.rst b/CAN-binder/libs/nanopb/docs/reference.rst deleted file mode 100644 index e59a0c94..00000000 --- a/CAN-binder/libs/nanopb/docs/reference.rst +++ /dev/null @@ -1,770 +0,0 @@ -===================== -Nanopb: API reference -===================== - -.. include :: menu.rst - -.. contents :: - - - - -Compilation options -=================== -The following options can be specified in one of two ways: - -1. Using the -D switch on the C compiler command line. -2. By #defining them at the top of pb.h. - -You must have the same settings for the nanopb library and all code that -includes pb.h. - -============================ ================================================ -PB_NO_PACKED_STRUCTS Disable packed structs. Increases RAM usage but - is necessary on some platforms that do not - support unaligned memory access. -PB_ENABLE_MALLOC Set this to enable dynamic allocation support - in the decoder. -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. -PB_SYSTEM_HEADER Replace the standard header files with a single - header file. It should define all the required - functions and typedefs listed on the - `overview page`_. Value must include quotes, - for example *#define PB_SYSTEM_HEADER "foo.h"*. -============================ ================================================ - -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). - -.. _`overview page`: index.html#compiler-requirements - - -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). -int_size Override the integer type of a field. - (To use e.g. uint8_t to save RAM.) -type Type of the generated field. Default value - is *FT_DEFAULT*, which selects automatically. - You can use *FT_CALLBACK*, *FT_POINTER*, - *FT_STATIC* or *FT_IGNORE* to - force a callback field, a dynamically - allocated 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. -skip_message Skip the whole message from generation. -no_unions Generate 'oneof' fields as optional fields - instead of C unions. -msgid Specifies a unique id for this message type. - Can be used by user code as an identifier. -anonymous_oneof Generate 'oneof' fields as anonymous unions. -fixed_length Generate 'bytes' fields with constant length. -============================ ================================================ - -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'. :: - - # myproto.proto - message MyMessage { - required string name = 1; - repeated int32 ids = 4; - } - -:: - - # myproto.options - MyMessage.name max_size:40 - MyMessage.ids max_count:5 - -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"; - - message MyMessage { - required string name = 1 [(nanopb).max_size = 40]; - repeated int32 ids = 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 -==== - -pb_byte_t ---------- -Type used for storing byte-sized data, such as raw binary input and bytes-type fields. :: - - typedef uint_least8_t pb_byte_t; - -For most platforms this is equivalent to `uint8_t`. Some platforms however do not support -8-bit variables, and on those platforms 16 or 32 bits need to be used for each byte. - -pb_type_t ---------- -Type used to store the type of each field, to control the encoder/decoder behaviour. :: - - typedef uint_least8_t pb_type_t; - -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_UVARINT 0x01 Unsigned integer. -PB_LTYPE_SVARINT 0x02 Integer, zigzag encoded. -PB_LTYPE_FIXED32 0x03 32-bit integer or floating point. -PB_LTYPE_FIXED64 0x04 64-bit integer or floating point. -PB_LTYPE_BYTES 0x05 Structure with *size_t* field and byte array. -PB_LTYPE_STRING 0x06 Null-terminated string. -PB_LTYPE_SUBMESSAGE 0x07 Submessage structure. -PB_LTYPE_EXTENSION 0x08 Point to *pb_extension_t*. -PB_LTYPE_FIXED_LENGTH_BYTES 0x09 Inline *pb_byte_t* array of fixed size. -=========================== ===== ================================================ - -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_* boolean to specify - whether the field is present. - (Unless it is a callback) -PB_HTYPE_REPEATED 0x20 A repeated field with preallocated array. - Separate *_count* for number of items. - (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. :: - - typedef struct pb_field_s pb_field_t; - struct pb_field_s { - pb_size_t tag; - pb_type_t type; - pb_size_t data_offset; - pb_ssize_t size_offset; - pb_size_t data_size; - pb_size_t array_size; - const void *ptr; - } pb_packed; - -:tag: Tag number of the field or 0 to terminate a list of fields. -: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. -:array_size: Maximum number of entries in an array, if it is an array type. -:ptr: Pointer to default value for optional fields, or to submessage description for PB_LTYPE_SUBMESSAGE. - -The *uint8_t* datatypes limit the maximum size of a single item to 255 bytes and arrays to 255 items. Compiler will give error if the values are too large. The types can be changed to larger ones by defining *PB_FIELD_16BIT*. - -pb_bytes_array_t ----------------- -An byte array with a field for storing the length:: - - typedef struct { - pb_size_t size; - pb_byte_t bytes[1]; - } pb_bytes_array_t; - -In an actual array, the length of *bytes* may be different. - -pb_callback_t -------------- -Part of a message structure, for fields with type PB_HTYPE_CALLBACK:: - - 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, void * const *arg); - } funcs; - - void *arg; - }; - -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_wire_type_t --------------- -Protocol Buffers wire types. These are used with `pb_encode_tag`_. :: - - typedef enum { - PB_WT_VARINT = 0, - PB_WT_64BIT = 1, - PB_WT_STRING = 2, - PB_WT_32BIT = 5 - } pb_wire_type_t; - -pb_extension_type_t -------------------- -Defines the handler functions and auxiliary data for a field that extends -another message. Usually autogenerated by *nanopb_generator.py*:: - - typedef struct { - bool (*decode)(pb_istream_t *stream, pb_extension_t *extension, - uint32_t tag, pb_wire_type_t wire_type); - bool (*encode)(pb_ostream_t *stream, const pb_extension_t *extension); - const void *arg; - } pb_extension_type_t; - -In the normal case, the function pointers are *NULL* and the decoder and -encoder use their internal implementations. The internal implementations -assume that *arg* points to a *pb_field_t* that describes the field in question. - -To implement custom processing of unknown fields, you can provide pointers -to your own functions. Their functionality is mostly the same as for normal -callback fields, except that they get called for any unknown field when decoding. - -pb_extension_t --------------- -Ties together the extension field type and the storage for the field value:: - - typedef struct { - const pb_extension_type_t *type; - void *dest; - pb_extension_t *next; - bool found; - } pb_extension_t; - -:type: Pointer to the structure that defines the callback functions. -:dest: Pointer to the variable that stores the field value - (as used by the default extension callback functions.) -:next: Pointer to the next extension handler, or *NULL*. -:found: Decoder sets this to true if the extension was found. - -PB_GET_ERROR ------------- -Get the current error message from a stream, or a placeholder string if -there is no error message:: - - #define PB_GET_ERROR(stream) (string expression) - -This should be used for printing errors, for example:: - - if (!pb_decode(...)) - { - printf("Decode failed: %s\n", PB_GET_ERROR(stream)); - } - -The macro only returns pointers to constant strings (in code memory), -so that there is no need to release the returned pointer. - -PB_RETURN_ERROR ---------------- -Set the error message and return false:: - - #define PB_RETURN_ERROR(stream,msg) (sets error and returns false) - -This should be used to handle error conditions inside nanopb functions -and user callback functions:: - - if (error_condition) - { - PB_RETURN_ERROR(stream, "something went wrong"); - } - -The *msg* parameter must be a constant string. - - - -pb_encode.h -=========== - -pb_ostream_from_buffer ----------------------- -Constructs an output stream for writing into a memory buffer. This is just a helper function, it doesn't do anything you couldn't do yourself in a callback function. It uses an internal callback that stores the pointer in stream *state* field. :: - - pb_ostream_t pb_ostream_from_buffer(pb_byte_t *buf, size_t bufsize); - -:buf: Memory buffer to write into. -:bufsize: Maximum number of bytes to write. -:returns: An output stream. - -After writing, you can check *stream.bytes_written* to find out how much valid data there is in the buffer. - -pb_write --------- -Writes data to an output stream. Always use this function, instead of trying to call stream callback manually. :: - - bool pb_write(pb_ostream_t *stream, const pb_byte_t *buf, size_t count); - -:stream: Output stream to write to. -:buf: Pointer to buffer with the data to be written. -:count: Number of bytes to write. -:returns: True on success, false if maximum length is exceeded or an IO error happens. - -If an error happens, *bytes_written* is not incremented. Depending on the callback used, calling pb_write again after it has failed once may be dangerous. Nanopb itself never does this, instead it returns the error to user application. The builtin pb_ostream_from_buffer is safe to call again after failed write. - -pb_encode ---------- -Encodes the contents of a structure as a protocol buffers message and writes it to output stream. :: - - bool pb_encode(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); - -:stream: Output stream to write to. -:fields: A field description array, usually autogenerated. -:src_struct: Pointer to the data that will be serialized. -:returns: True on success, false on IO error, on detectable errors in field description, or if a field encoder returns false. - -Normally pb_encode simply walks through the fields description array and serializes each field in turn. However, submessages must be serialized twice: first to calculate their size and then to actually write them to output. This causes some constraints for callback fields, which must return the same data on every call. - -pb_encode_delimited -------------------- -Calculates the length of the message, encodes it as varint and then encodes the message. :: - - bool pb_encode_delimited(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); - -(parameters are the same as for `pb_encode`_.) - -A common way to indicate the message length in Protocol Buffers is to prefix it with a varint. -This function does this, and it is compatible with *parseDelimitedFrom* in Google's protobuf library. - -.. sidebar:: Encoding fields manually - - The functions with names *pb_encode_\** are used when dealing with callback fields. The typical reason for using callbacks is to have an array of unlimited size. In that case, `pb_encode`_ will call your callback function, which in turn will call *pb_encode_\** functions repeatedly to write out values. - - The tag of a field must be encoded separately with `pb_encode_tag_for_field`_. After that, you can call exactly one of the content-writing functions to encode the payload of the field. For repeated fields, you can repeat this process multiple times. - - Writing packed arrays is a little bit more involved: you need to use `pb_encode_tag` and specify `PB_WT_STRING` as the wire type. Then you need to know exactly how much data you are going to write, and use `pb_encode_varint`_ to write out the number of bytes before writing the actual data. Substreams can be used to determine the number of bytes beforehand; see `pb_encode_submessage`_ source code for an example. - -pb_get_encoded_size -------------------- -Calculates the length of the encoded message. :: - - bool pb_get_encoded_size(size_t *size, const pb_field_t fields[], const void *src_struct); - -:size: Calculated size of the encoded message. -:fields: A field description array, usually autogenerated. -:src_struct: Pointer to the data that will be serialized. -:returns: True on success, false on detectable errors in field description or if a field encoder returns false. - -pb_encode_tag -------------- -Starts a field in the Protocol Buffers binary format: encodes the field number and the wire type of the data. :: - - bool pb_encode_tag(pb_ostream_t *stream, pb_wire_type_t wiretype, uint32_t field_number); - -:stream: Output stream to write to. 1-5 bytes will be written. -:wiretype: PB_WT_VARINT, PB_WT_64BIT, PB_WT_STRING or PB_WT_32BIT -:field_number: Identifier for the field, defined in the .proto file. You can get it from field->tag. -:returns: True on success, false on IO error. - -pb_encode_tag_for_field ------------------------ -Same as `pb_encode_tag`_, except takes the parameters from a *pb_field_t* structure. :: - - bool pb_encode_tag_for_field(pb_ostream_t *stream, const pb_field_t *field); - -:stream: Output stream to write to. 1-5 bytes will be written. -:field: Field description structure. Usually autogenerated. -:returns: True on success, false on IO error or unknown field type. - -This function only considers the LTYPE of the field. You can use it from your field callbacks, because the source generator writes correct LTYPE also for callback type fields. - -Wire type mapping is as follows: - -============================================= ============ -LTYPEs Wire type -============================================= ============ -VARINT, UVARINT, SVARINT PB_WT_VARINT -FIXED64 PB_WT_64BIT -STRING, BYTES, SUBMESSAGE, FIXED_LENGTH_BYTES PB_WT_STRING -FIXED32 PB_WT_32BIT -============================================= ============ - -pb_encode_varint ----------------- -Encodes a signed or unsigned integer in the varint_ format. Works for fields of type `bool`, `enum`, `int32`, `int64`, `uint32` and `uint64`:: - - bool pb_encode_varint(pb_ostream_t *stream, uint64_t value); - -:stream: Output stream to write to. 1-10 bytes will be written. -:value: Value to encode. Just cast e.g. int32_t directly to uint64_t. -:returns: True on success, false on IO error. - -.. _varint: http://code.google.com/apis/protocolbuffers/docs/encoding.html#varints - -pb_encode_svarint ------------------ -Encodes a signed integer in the 'zig-zagged' format. Works for fields of type `sint32` and `sint64`:: - - bool pb_encode_svarint(pb_ostream_t *stream, int64_t value); - -(parameters are the same as for `pb_encode_varint`_ - -pb_encode_string ----------------- -Writes the length of a string as varint and then contents of the string. Works for fields of type `bytes` and `string`:: - - bool pb_encode_string(pb_ostream_t *stream, const pb_byte_t *buffer, size_t size); - -:stream: Output stream to write to. -:buffer: Pointer to string data. -:size: Number of bytes in the string. Pass `strlen(s)` for strings. -:returns: True on success, false on IO error. - -pb_encode_fixed32 ------------------ -Writes 4 bytes to stream and swaps bytes on big-endian architectures. Works for fields of type `fixed32`, `sfixed32` and `float`:: - - bool pb_encode_fixed32(pb_ostream_t *stream, const void *value); - -:stream: Output stream to write to. -:value: Pointer to a 4-bytes large C variable, for example `uint32_t foo;`. -:returns: True on success, false on IO error. - -pb_encode_fixed64 ------------------ -Writes 8 bytes to stream and swaps bytes on big-endian architecture. Works for fields of type `fixed64`, `sfixed64` and `double`:: - - bool pb_encode_fixed64(pb_ostream_t *stream, const void *value); - -:stream: Output stream to write to. -:value: Pointer to a 8-bytes large C variable, for example `uint64_t foo;`. -:returns: True on success, false on IO error. - -pb_encode_submessage --------------------- -Encodes a submessage field, including the size header for it. Works for fields of any message type:: - - bool pb_encode_submessage(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct); - -:stream: Output stream to write to. -:fields: Pointer to the autogenerated field description array for the submessage type, e.g. `MyMessage_fields`. -:src: Pointer to the structure where submessage data is. -:returns: True on success, false on IO errors, pb_encode errors or if submessage size changes between calls. - -In Protocol Buffers format, the submessage size must be written before the submessage contents. Therefore, this function has to encode the submessage twice in order to know the size beforehand. - -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 -=========== - -pb_istream_from_buffer ----------------------- -Helper function for creating an input stream that reads data from a memory buffer. :: - - pb_istream_t pb_istream_from_buffer(const pb_byte_t *buf, size_t bufsize); - -:buf: Pointer to byte array to read from. -:bufsize: Size of the byte array. -:returns: An input stream ready to use. - -pb_read -------- -Read data from input stream. Always use this function, don't try to call the stream callback directly. :: - - bool pb_read(pb_istream_t *stream, pb_byte_t *buf, size_t count); - -:stream: Input stream to read from. -:buf: Buffer to store the data to, or NULL to just read data without storing it anywhere. -:count: Number of bytes to read. -:returns: True on success, false if *stream->bytes_left* is less than *count* or if an IO error occurs. - -End of file is signalled by *stream->bytes_left* being zero after pb_read returns false. - -pb_decode ---------- -Read and decode all fields of a structure. Reads until EOF on input stream. :: - - bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); - -:stream: Input stream to read from. -:fields: A field description array. Usually autogenerated. -:dest_struct: Pointer to structure where data will be stored. -:returns: True on success, false on IO error, on detectable errors in field description, if a field encoder returns false or if a required field is missing. - -In Protocol Buffers binary format, EOF is only allowed between fields. If it happens anywhere else, pb_decode will return *false*. If pb_decode returns false, you cannot trust any of the data in the structure. - -In addition to EOF, the pb_decode implementation supports terminating a message with a 0 byte. This is compatible with the official Protocol Buffers because 0 is never a valid field tag. - -For optional fields, this function applies the default value and sets *has_* to false if the field is not present. - -If *PB_ENABLE_MALLOC* is defined, this function may allocate storage for any pointer type fields. -In this case, you have to call `pb_release`_ to release the memory after you are done with the message. -On error return `pb_decode` will release the memory itself. - -pb_decode_noinit ----------------- -Same as `pb_decode`_, except does not apply the default values to fields. :: - - bool pb_decode_noinit(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); - -(parameters are the same as for `pb_decode`_.) - -The destination structure should be filled with zeros before calling this function. Doing a *memset* manually can be slightly faster than using `pb_decode`_ if you don't need any default values. - -In addition to decoding a single message, this function can be used to merge two messages, so that -values from previous message will remain if the new message does not contain a field. - -This function *will not* release the message even on error return. If you use *PB_ENABLE_MALLOC*, -you will need to call `pb_release`_ yourself. - -pb_decode_delimited -------------------- -Same as `pb_decode`_, except that it first reads a varint with the length of the message. :: - - bool pb_decode_delimited(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct); - -(parameters are the same as for `pb_decode`_.) - -A common method to indicate message size in Protocol Buffers is to prefix it with a varint. -This function is compatible with *writeDelimitedTo* in the Google's Protocol Buffers library. - -pb_release ----------- -Releases any dynamically allocated fields:: - - void pb_release(const pb_field_t fields[], void *dest_struct); - -:fields: A field description array. Usually autogenerated. -:dest_struct: Pointer to structure where data is stored. If NULL, function does nothing. - -This function is only available if *PB_ENABLE_MALLOC* is defined. It will release any -pointer type fields in the structure and set the pointers to NULL. - -pb_decode_tag -------------- -Decode the tag that comes before field in the protobuf encoding:: - - bool pb_decode_tag(pb_istream_t *stream, pb_wire_type_t *wire_type, uint32_t *tag, bool *eof); - -:stream: Input stream to read from. -:wire_type: Pointer to variable where to store the wire type of the field. -:tag: Pointer to variable where to store the tag of the field. -:eof: Pointer to variable where to store end-of-file status. -:returns: True on success, false on error or EOF. - -When the message (stream) ends, this function will return false and set *eof* to true. On other -errors, *eof* will be set to false. - -pb_skip_field -------------- -Remove the data for a field from the stream, without actually decoding it:: - - bool pb_skip_field(pb_istream_t *stream, pb_wire_type_t wire_type); - -:stream: Input stream to read from. -:wire_type: Type of field to skip. -:returns: True on success, false on IO error. - -.. sidebar:: Decoding fields manually - - The functions with names beginning with *pb_decode_* are used when dealing with callback fields. The typical reason for using callbacks is to have an array of unlimited size. In that case, `pb_decode`_ will call your callback function repeatedly, which can then store the values into e.g. filesystem in the order received in. - - For decoding numeric (including enumerated and boolean) values, use `pb_decode_varint`_, `pb_decode_svarint`_, `pb_decode_fixed32`_ and `pb_decode_fixed64`_. They take a pointer to a 32- or 64-bit C variable, which you may then cast to smaller datatype for storage. - - For decoding strings and bytes fields, the length has already been decoded. You can therefore check the total length in *stream->bytes_left* and read the data using `pb_read`_. - - Finally, for decoding submessages in a callback, simply use `pb_decode`_ and pass it the *SubMessage_fields* descriptor array. - -pb_decode_varint ----------------- -Read and decode a varint_ encoded integer. :: - - bool pb_decode_varint(pb_istream_t *stream, uint64_t *dest); - -:stream: Input stream to read from. 1-10 bytes will be read. -:dest: Storage for the decoded integer. Value is undefined on error. -:returns: True on success, false if value exceeds uint64_t range or an IO error happens. - -pb_decode_svarint ------------------ -Similar to `pb_decode_varint`_, except that it performs zigzag-decoding on the value. This corresponds to the Protocol Buffers *sint32* and *sint64* datatypes. :: - - bool pb_decode_svarint(pb_istream_t *stream, int64_t *dest); - -(parameters are the same as `pb_decode_varint`_) - -pb_decode_fixed32 ------------------ -Decode a *fixed32*, *sfixed32* or *float* value. :: - - bool pb_decode_fixed32(pb_istream_t *stream, void *dest); - -:stream: Input stream to read from. 4 bytes will be read. -:dest: Pointer to destination *int32_t*, *uint32_t* or *float*. -:returns: True on success, false on IO errors. - -This function reads 4 bytes from the input stream. -On big endian architectures, it then reverses the order of the bytes. -Finally, it writes the bytes to *dest*. - -pb_decode_fixed64 ------------------ -Decode a *fixed64*, *sfixed64* or *double* value. :: - - bool pb_decode_fixed64(pb_istream_t *stream, void *dest); - -:stream: Input stream to read from. 8 bytes will be read. -:dest: Pointer to destination *int64_t*, *uint64_t* or *double*. -:returns: True on success, false on IO errors. - -Same as `pb_decode_fixed32`_, except this reads 8 bytes. - -pb_make_string_substream ------------------------- -Decode the length for a field with wire type *PB_WT_STRING* and create a substream for reading the data. :: - - bool pb_make_string_substream(pb_istream_t *stream, pb_istream_t *substream); - -:stream: Original input stream to read the length and data from. -:substream: New substream that has limited length. Filled in by the function. -:returns: True on success, false if reading the length fails. - -This function uses `pb_decode_varint`_ to read an integer from the stream. This is interpreted as a number of bytes, and the substream is set up so that its `bytes_left` is initially the same as the length, and its callback function and state the same as the parent stream. - -pb_close_string_substream -------------------------- -Close the substream created with `pb_make_string_substream`_. :: - - void pb_close_string_substream(pb_istream_t *stream, pb_istream_t *substream); - -:stream: Original input stream to read the length and data from. -:substream: Substream to close - -This function copies back the state from the substream to the parent stream. -It must be called after done with the substream. diff --git a/CAN-binder/libs/nanopb/docs/security.rst b/CAN-binder/libs/nanopb/docs/security.rst deleted file mode 100644 index d8546122..00000000 --- a/CAN-binder/libs/nanopb/docs/security.rst +++ /dev/null @@ -1,84 +0,0 @@ -====================== -Nanopb: Security model -====================== - -.. include :: menu.rst - -.. contents :: - - - -Importance of security in a Protocol Buffers library -==================================================== -In the context of protocol buffers, security comes into play when decoding -untrusted data. Naturally, if the attacker can modify the contents of a -protocol buffers message, he can feed the application any values possible. -Therefore the application itself must be prepared to receive untrusted values. - -Where nanopb plays a part is preventing the attacker from running arbitrary -code on the target system. Mostly this means that there must not be any -possibility to cause buffer overruns, memory corruption or invalid pointers -by the means of crafting a malicious message. - -Division of trusted and untrusted data -====================================== -The following data is regarded as **trusted**. It must be under the control of -the application writer. Malicious data in these structures could cause -security issues, such as execution of arbitrary code: - -1. Callback, pointer and extension fields in message structures given to - pb_encode() and pb_decode(). These fields are memory pointers, and are - generated depending on the message definition in the .proto file. -2. The automatically generated field definitions, i.e. *pb_field_t* lists. -3. Contents of the *pb_istream_t* and *pb_ostream_t* structures (this does not - mean the contents of the stream itself, just the stream definition). - -The following data is regarded as **untrusted**. Invalid/malicious data in -these will cause "garbage in, garbage out" behaviour. It will not cause -buffer overflows, information disclosure or other security problems: - -1. All data read from *pb_istream_t*. -2. All fields in message structures, except: - - - callbacks (*pb_callback_t* structures) - - pointer fields (malloc support) and *_count* fields for pointers - - extensions (*pb_extension_t* structures) - -Invariants -========== -The following invariants are maintained during operation, even if the -untrusted data has been maliciously crafted: - -1. Nanopb will never read more than *bytes_left* bytes from *pb_istream_t*. -2. Nanopb will never write more than *max_size* bytes to *pb_ostream_t*. -3. Nanopb will never access memory out of bounds of the message structure. -4. After pb_decode() returns successfully, the message structure will be - internally consistent: - - - The *count* fields of arrays will not exceed the array size. - - The *size* field of bytes will not exceed the allocated size. - - All string fields will have null terminator. - -5. After pb_encode() returns successfully, the resulting message is a valid - protocol buffers message. (Except if user-defined callbacks write incorrect - data.) - -Further considerations -====================== -Even if the nanopb library is free of any security issues, there are still -several possible attack vectors that the application author must consider. -The following list is not comprehensive: - -1. Stack usage may depend on the contents of the message. The message - definition places an upper bound on how much stack will be used. Tests - should be run with all fields present, to record the maximum possible - stack usage. -2. Callbacks can do anything. The code for the callbacks must be carefully - checked if they are used with untrusted data. -3. If using stream input, a maximum size should be set in *pb_istream_t* to - stop a denial of service attack from using an infinite message. -4. If using network sockets as streams, a timeout should be set to stop - denial of service attacks. -5. If using *malloc()* support, some method of limiting memory use should be - employed. This can be done by defining custom *pb_realloc()* function. - Nanopb will properly detect and handle failed memory allocations. -- cgit 1.2.3-korg