aboutsummaryrefslogtreecommitdiffstats
path: root/gdb/gdb-on-target.in
blob: 360c8608d49f802815c7d6316a59c66e4dd51019 (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13

# gdb-remote.init file for IDE
# Object: allow to use standard gdb to remote debug a target
# Usage: remote-target-populate update script under ./build directory
# Author: Fulup Ar Foll (IoT.bzh)
# Reference: https://blog.flameeyes.eu/2010/02/remote-debugging-with-gdb-part-2-gdb/

# Start gdbserver on target and connect through SSH link
target remote | ssh @RSYNC_TARGET@ gdbserver - afb-daemon --port=@AFB_REMPORT@ --workdir=@RSYNC_PREFIX@/@PROJECT_NAME@ --roothttp=./htdocs --ldpath=./lib --verbose --token=@AFB_TOKEN@

# Replace run by continue (gdb use 'run' when gdbserver wants 'continue')
define run
continue
end
6; font-weight: bold } /* Name.Namespace */ .highlight .py { color: #336699; font-weight: bold } /* Name.Property */ .highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #336699 } /* Name.Variable */ .highlight .ow { color: #008800 } /* Operator.Word */ .highlight .w { color: #bbbbbb } /* Text.Whitespace */ .highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */ .highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */ .highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */ .highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */ .highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */ .highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */ .highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */ .highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */ .highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */ .highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */ .highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */ .highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */ .highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */ .highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */ .highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */ .highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */ .highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */ .highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */ .highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */
=============================================
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.

__ http://code.google.com/apis/protocolbuffers/

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 string *nanopb_generator.py* accomplishes this.

So a typical project might include these files:

1) Nanopb runtime library:
    - pb.h
    - 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.c (autogenerated, contains initializers for const arrays)
    - person.h (autogenerated, contains type declarations)

Features and limitations
========================

**Features**

#) Pure C runtime
#) 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.
#) You can use either encoder or decoder alone to cut the code size in half.

**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.
#) 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.
#) 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.

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 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.

Debugging and testing
=====================
Extensive unittests are included under the *tests* folder. Just type *make* there to run the tests.

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.

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.