From 85e0afd894daf851baca8ecd50ebae3cdba40e65 Mon Sep 17 00:00:00 2001 From: Petteri Aimonen Date: Fri, 4 Nov 2011 07:22:05 +0000 Subject: [PATCH] Some additions to documentation git-svn-id: https://svn.kapsi.fi/jpa/nanopb@1003 e3a754e5-d11d-0410-8d38-ebb782a927b9 --- docs/Makefile | 8 +- docs/generator_flow.svg | 2869 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 13 +- 3 files changed, 2883 insertions(+), 7 deletions(-) create mode 100644 docs/generator_flow.svg diff --git a/docs/Makefile b/docs/Makefile index d1d9587d..3c953990 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,4 +1,8 @@ -all: index.html concepts.html reference.html +all: index.html concepts.html reference.html \ + generator_flow.png + +%.png: %.svg + rsvg $< $@ %.html: %.rst - rst2html --stylesheet=lsr.css --link-stylesheet $< $@ \ No newline at end of file + rst2html --stylesheet=lsr.css --link-stylesheet $< $@ diff --git a/docs/generator_flow.svg b/docs/generator_flow.svg new file mode 100644 index 00000000..e30277a7 --- /dev/null +++ b/docs/generator_flow.svg @@ -0,0 +1,2869 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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/docs/index.rst b/docs/index.rst index 1022a1b2..31d781ea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,9 +13,11 @@ 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: @@ -25,8 +27,8 @@ So a typical project might include these files: - pb_encode.h and pb_encode.c (needed for encoding messages) 2) Protocol description (you can have many): - person.proto (just an example) - - person.c (autogenerated, contains initializers for const arrays) - - person.h (autogenerated, contains type declarations) + - person.pb.c (autogenerated, contains initializers for const arrays) + - person.pb.h (autogenerated, contains type declarations) Features and limitations ======================== @@ -37,7 +39,7 @@ Features and limitations #) Small code size (2–10 kB depending on processor) #) Small ram usage (typically 200 bytes) #) 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. **Limitations** @@ -48,6 +50,7 @@ Features and limitations #) 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. -- 2.16.6