X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Findex.rst;h=cb7a201f4cd0c5ede7ea4cb7a733964482ff6230;hb=b663909fb6e86f0ae0f450523e72fb7fbfb719ab;hp=f2f8dcfd4f46113d95754fa19c6693c15a302cdd;hpb=5a9f85b87615078868d3b394370a30b550186cce;p=apps%2Fagl-service-can-low-level.git

diff --git a/docs/index.rst b/docs/index.rst
index f2f8dcfd..cb7a201f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,20 +13,22 @@ 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*.
+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 string *nanopb_generator.py* accomplishes this.
+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_decode.h and pb_decode.c
-    - pb_encode.h and pb_encode.c
+    - 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
-    - person.c (autogenerated, contains initializers for const arrays)
-    - person.h (autogenerated, contains type declarations)
+    - person.proto (just an example)
+    - person.pb.c (autogenerated, contains initializers for const arrays)
+    - person.pb.h (autogenerated, contains type declarations)
 
 Features and limitations
 ========================
@@ -34,20 +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 is stored on the stack.
+#) No malloc needed: everything can be allocated statically or on the stack.
 #) You can use either encoder or decoder alone to cut the code size in half.
+#) Support for most protobuf features, including: all data types, nested submessages, default values, repeated and optional fields, packed arrays.
+#) Callback mechanism for handling messages larger than can fit in available RAM.
+#) Extensive set of tests.
 
 **Limitations**
 
 #) User must provide callbacks when decoding arrays or strings without maximum size. Malloc support could be added as a separate module.
-#) Some speed has been sacrificed for code size. For example varint calculations are always done in 64 bits.
+#) Some speed has been sacrificed for code size.
 #) Encoding is focused on writing to streams. For memory buffers only it could be made more efficient.
 #) The deprecated Protocol Buffers feature called "groups" is not supported.
 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
 #) Unknown fields are not preserved when decoding and re-encoding a message.
+#) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string.
+#) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format.
+#) Cyclic references between messages are supported only in callback mode.
 
 Getting started
 ===============
@@ -58,12 +66,12 @@ For starters, consider this simple message::
     required int32 value = 1;
  }
 
-Save this in *example.proto* and compile it::
+Save this in *message.proto* and compile it::
 
     user@host:~$ protoc -omessage.pb message.proto
-    user@host:~$ python ../generator/nanopb_generator.py message.pb
+    user@host:~$ python nanopb/generator/nanopb_generator.py message.pb
 
-You should now have in *example.h*::
+You should now have in *message.pb.h*::
 
  typedef struct {
     int32_t value;
@@ -80,10 +88,24 @@ Now in your main program do this to encode a message::
 
 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 example.proto* to verify its validity.
+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.
+
+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 should be able to find suitable replacements online. Mostly the requirements are very simple, just a few basic functions and typedefs.
+
+Alternatively, you can define *PB_SYSTEM_HEADER*, which should be the name of a single header file including all the necessary definitions.
+
+Debugging and testing
+=====================
+Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests.
 
-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.