X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Findex.rst;h=27840f7d9f91972bb5b59bf21d3be578b29a98c5;hb=287207841db5df93cf7ff9c71a5f1548deb26b09;hp=31d781ea74d64d62033b0c1d7eaad59b4b420985;hpb=85e0afd894daf851baca8ecd50ebae3cdba40e65;p=apps%2Fagl-service-can-low-level.git diff --git a/docs/index.rst b/docs/index.rst index 31d781ea..27840f7d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,23 +36,26 @@ Features and limitations **Features** #) Pure C runtime -#) Small code size (2–10 kB depending on processor) -#) Small ram usage (typically 200 bytes) +#) Small code size (2–10 kB depending on processor, plus any message definitions) +#) Small ram usage (typically ~300 bytes, plus any message structs) #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically. #) No malloc needed: everything can be allocated statically or on the stack. #) You can use either encoder or decoder alone to cut the code size in half. +#) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, packed arrays, extension fields. +#) Callback mechanism for handling messages larger than can fit in available RAM. +#) Extensive set of tests. **Limitations** #) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module. -#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits. +#) Some speed has been sacrificed for code size. #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient. #) The deprecated Protocol Buffers feature called "groups" is not supported. #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file. #) Unknown fields are not preserved when decoding and re-encoding a message. #) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string. #) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format. -#) Cyclic references between messages are not supported. They could be supported in callback-mode if there was an option in the generator to set the mode. +#) Cyclic references between messages are supported only in callback mode. Getting started =============== @@ -87,27 +90,37 @@ 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 complete examples of the simple cases, see *tests/test_decode1.c* and *tests/test_encode1.c*. For an example with network interface, see the *example* subdirectory. +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: +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 should be able to find suitable replacements online. Mostly the requirements are very simple, just a few basic functions and typedefs. +If these header files do not come with your compiler, you can use the +file *compat/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. -Debugging and testing -===================== -Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests. +To use the pb_syshdr.h, define *PB_SYSTEM_HEADER* to be the name of your custom +header file. It 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/ -This also generates a file called *breakpoints* which includes all lines returning *false* in nanopb. You can use this in gdb by typing *source breakpoints*, after which gdb will break on first nanopb error. +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*. -Wishlist -======== -#) A specialized encoder for encoding to a memory buffer. Should serialize in reverse order to avoid having to determine submessage size beforehand. -#) A cleaner rewrite of the Python-based source generator. -#) Better performance for 16- and 8-bit platforms: use smaller datatypes where possible.