diff options
Diffstat (limited to 'doc/developer')
21 files changed, 62 insertions, 42 deletions
diff --git a/doc/developer/building-frr-for-centos6.rst b/doc/developer/building-frr-for-centos6.rst index 7a7af42119..233d089f79 100644 --- a/doc/developer/building-frr-for-centos6.rst +++ b/doc/developer/building-frr-for-centos6.rst @@ -46,7 +46,7 @@ Add packages: sudo yum install git autoconf automake libtool make \ readline-devel texinfo net-snmp-devel groff pkgconfig \ json-c-devel pam-devel flex epel-release c-ares-devel libcap-devel \ - elfutils-libelf-devel + elfutils-libelf-devel protobuf-c-devel Install newer version of bison (CentOS 6 package source is too old) from CentOS 7: diff --git a/doc/developer/building-frr-for-centos7.rst b/doc/developer/building-frr-for-centos7.rst index c40b5de594..e6da830194 100644 --- a/doc/developer/building-frr-for-centos7.rst +++ b/doc/developer/building-frr-for-centos7.rst @@ -22,7 +22,7 @@ Add packages: readline-devel texinfo net-snmp-devel groff pkgconfig \ json-c-devel pam-devel bison flex pytest c-ares-devel \ python-devel python-sphinx libcap-devel \ - elfutils-libelf-devel libunwind-devel + elfutils-libelf-devel libunwind-devel protobuf-c-devel .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-centos8.rst b/doc/developer/building-frr-for-centos8.rst index 659752f6df..6d18e7be93 100644 --- a/doc/developer/building-frr-for-centos8.rst +++ b/doc/developer/building-frr-for-centos8.rst @@ -15,7 +15,8 @@ Add packages: automake libtool make readline-devel texinfo net-snmp-devel pkgconfig \ groff pkgconfig json-c-devel pam-devel bison flex python2-pytest \ c-ares-devel python2-devel libcap-devel \ - elfutils-libelf-devel libunwind-devel + elfutils-libelf-devel libunwind-devel \ + protobuf-c-devel .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-debian8.rst b/doc/developer/building-frr-for-debian8.rst index 5e58854ed7..7071cb660d 100644 --- a/doc/developer/building-frr-for-debian8.rst +++ b/doc/developer/building-frr-for-debian8.rst @@ -18,7 +18,7 @@ Add packages: sudo apt-get install git autoconf automake libtool make \ libreadline-dev texinfo libjson-c-dev pkg-config bison flex python3-pip \ libc-ares-dev python3-dev python3-sphinx build-essential \ - libsnmp-dev libcap-dev libelf-dev + libsnmp-dev libcap-dev libelf-dev libprotobuf-c-dev protobuf-c-compiler Install newer pytest (>3.0) from pip diff --git a/doc/developer/building-frr-for-debian9.rst b/doc/developer/building-frr-for-debian9.rst index b2fdef9990..1b2f1b933a 100644 --- a/doc/developer/building-frr-for-debian9.rst +++ b/doc/developer/building-frr-for-debian9.rst @@ -11,7 +11,8 @@ Add packages: sudo apt-get install git autoconf automake libtool make \ libreadline-dev texinfo libjson-c-dev pkg-config bison flex \ libc-ares-dev python3-dev python3-pytest python3-sphinx build-essential \ - libsnmp-dev libcap-dev libelf-dev libunwind-dev + libsnmp-dev libcap-dev libelf-dev libunwind-dev \ + libprotobuf-c-dev protobuf-c-compiler .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-fedora.rst b/doc/developer/building-frr-for-fedora.rst index aa10f1118d..35a24b2f43 100644 --- a/doc/developer/building-frr-for-fedora.rst +++ b/doc/developer/building-frr-for-fedora.rst @@ -15,7 +15,7 @@ Installing Dependencies readline-devel texinfo net-snmp-devel groff pkgconfig json-c-devel \ pam-devel python3-pytest bison flex c-ares-devel python3-devel \ python3-sphinx perl-core patch libcap-devel \ - elfutils-libelf-devel libunwind-devel + elfutils-libelf-devel libunwind-devel protobuf-c-devel .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-freebsd10.rst b/doc/developer/building-frr-for-freebsd10.rst index 5e70b81d43..707f1e7033 100644 --- a/doc/developer/building-frr-for-freebsd10.rst +++ b/doc/developer/building-frr-for-freebsd10.rst @@ -17,7 +17,8 @@ is first package install and asked) :: pkg install git autoconf automake libtool gmake json-c pkgconf \ - bison flex py36-pytest c-ares python3.6 py36-sphinx libunwind + bison flex py36-pytest c-ares python3.6 py36-sphinx libunwind \ + protobuf-c .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-freebsd11.rst b/doc/developer/building-frr-for-freebsd11.rst index 808207b831..af0b72b16d 100644 --- a/doc/developer/building-frr-for-freebsd11.rst +++ b/doc/developer/building-frr-for-freebsd11.rst @@ -17,7 +17,8 @@ is first package install and asked) .. code-block:: shell pkg install git autoconf automake libtool gmake json-c pkgconf \ - bison flex py36-pytest c-ares python3.6 py36-sphinx texinfo libunwind + bison flex py36-pytest c-ares python3.6 py36-sphinx texinfo libunwind \ + protobuf-c .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-freebsd9.rst b/doc/developer/building-frr-for-freebsd9.rst index 1e97749795..30332875a0 100644 --- a/doc/developer/building-frr-for-freebsd9.rst +++ b/doc/developer/building-frr-for-freebsd9.rst @@ -18,7 +18,7 @@ is first package install and asked) pkg install -y git autoconf automake libtool gmake \ pkgconf texinfo json-c bison flex py36-pytest c-ares \ - python3 py36-sphinx libexecinfo + python3 py36-sphinx libexecinfo protobuf-c Make sure there is no /usr/bin/flex preinstalled (and use the newly installed in /usr/local/bin): (FreeBSD frequently provides a older flex diff --git a/doc/developer/building-frr-for-netbsd6.rst b/doc/developer/building-frr-for-netbsd6.rst index a78f8b3c2f..8958862fea 100644 --- a/doc/developer/building-frr-for-netbsd6.rst +++ b/doc/developer/building-frr-for-netbsd6.rst @@ -23,7 +23,8 @@ Add packages: :: sudo pkg_add git autoconf automake libtool gmake openssl \ - pkg-config json-c py36-test python36 py36-sphinx + pkg-config json-c py36-test python36 py36-sphinx \ + protobuf-c Install SSL Root Certificates (for git https access): diff --git a/doc/developer/building-frr-for-netbsd7.rst b/doc/developer/building-frr-for-netbsd7.rst index a52ece19a1..e751ba338c 100644 --- a/doc/developer/building-frr-for-netbsd7.rst +++ b/doc/developer/building-frr-for-netbsd7.rst @@ -14,7 +14,8 @@ Install required packages :: sudo pkgin install git autoconf automake libtool gmake openssl \ - pkg-config json-c python36 py36-test py36-sphinx + pkg-config json-c python36 py36-test py36-sphinx \ + protobuf-c Install SSL Root Certificates (for git https access): diff --git a/doc/developer/building-frr-for-openbsd6.rst b/doc/developer/building-frr-for-openbsd6.rst index 88446685e0..00bc2e5f09 100644 --- a/doc/developer/building-frr-for-openbsd6.rst +++ b/doc/developer/building-frr-for-openbsd6.rst @@ -16,7 +16,7 @@ Add packages: pkg_add clang libcares python3 pkg_add git autoconf-2.69p2 automake-1.15.1 libtool bison - pkg_add gmake json-c py-test py-sphinx libexecinfo + pkg_add gmake json-c py-test py-sphinx libexecinfo protobuf-c Select Python2.7 as default (required for pytest) diff --git a/doc/developer/building-frr-for-opensuse.rst b/doc/developer/building-frr-for-opensuse.rst index 38346fe881..3ff445bcd0 100644 --- a/doc/developer/building-frr-for-opensuse.rst +++ b/doc/developer/building-frr-for-opensuse.rst @@ -14,7 +14,7 @@ Installing Dependencies readline-devel texinfo net-snmp-devel groff pkgconfig libjson-c-devel\ pam-devel python3-pytest bison flex c-ares-devel python3-devel\ python3-Sphinx perl patch libcap-devel libyang-devel \ - libelf-devel libunwind-devel + libelf-devel libunwind-devel protobuf-c .. include:: building-libunwind-note.rst diff --git a/doc/developer/building-frr-for-ubuntu1404.rst b/doc/developer/building-frr-for-ubuntu1404.rst index 2711e92b6f..cc6c3c03f3 100644 --- a/doc/developer/building-frr-for-ubuntu1404.rst +++ b/doc/developer/building-frr-for-ubuntu1404.rst @@ -18,6 +18,13 @@ Installing Dependencies .. include:: building-libyang.rst +Protobuf +^^^^^^^^ + +.. code-block:: console + + sudo apt-get install protobuf-c-compiler libprotobuf-c-dev + Building & Installing FRR ------------------------- diff --git a/doc/developer/building-frr-for-ubuntu1604.rst b/doc/developer/building-frr-for-ubuntu1604.rst index d79545c859..e5c2389f39 100644 --- a/doc/developer/building-frr-for-ubuntu1604.rst +++ b/doc/developer/building-frr-for-ubuntu1604.rst @@ -15,10 +15,17 @@ Installing Dependencies pkg-config libpam0g-dev libjson-c-dev bison flex python3-pytest \ libc-ares-dev python3-dev python-ipaddress python3-sphinx \ install-info build-essential libsnmp-dev perl libcap-dev \ - libelf-dev + libelf-dev libprotobuf-c-dev protobuf-c-compiler .. include:: building-libyang.rst +Protobuf +^^^^^^^^ + +.. code-block:: console + + sudo apt-get install protobuf-c-compiler libprotobuf-c-dev + Building & Installing FRR ------------------------- diff --git a/doc/developer/logging.rst b/doc/developer/logging.rst index e262f6af94..b7021b69a1 100644 --- a/doc/developer/logging.rst +++ b/doc/developer/logging.rst @@ -335,16 +335,16 @@ Time/interval formats FRR library helper formats ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. frrfmt:: %pTH (struct thread *) +.. frrfmt:: %pTH (struct event *) - Print remaining time on timer thread. Interval-printing flag characters + Print remaining time on timer event. Interval-printing flag characters listed above for ``%pTV`` can be added, e.g. ``%pTHtx``. ``NULL`` pointers are printed as ``-``. -.. frrfmt:: %pTHD (struct thread *) +.. frrfmt:: %pTHD (struct event *) - Print debugging information for given thread. Sample output: + Print debugging information for given event. Sample output: .. code-block:: none diff --git a/doc/developer/modules.rst b/doc/developer/modules.rst index e95f8a1b4a..0feac8e738 100644 --- a/doc/developer/modules.rst +++ b/doc/developer/modules.rst @@ -56,9 +56,9 @@ Basic boilerplate: #include "hook.h" #include "module.h" #include "libfrr.h" - #include "thread.h" + #include "frrevent.h" - static int module_late_init(struct thread_master *master) + static int module_late_init(struct event_loop *master) { /* Do initialization stuff here */ return 0; diff --git a/doc/developer/path-internals-pcep.rst b/doc/developer/path-internals-pcep.rst index ca318314f1..a6b22204c2 100644 --- a/doc/developer/path-internals-pcep.rst +++ b/doc/developer/path-internals-pcep.rst @@ -182,7 +182,7 @@ The controller is defined and implemented in `path_pcep_controller.[hc]`. Part of the controller code runs in FRR main thread and part runs in its own FRR pthread started to isolate the main thread from the PCCs' event loop. To communicate between the threads it uses FRR events, timers and -`thread_execute` calls. +`event_execute` calls. PCC diff --git a/doc/developer/process-architecture.rst b/doc/developer/process-architecture.rst index 37bd620f24..33ef278c4d 100644 --- a/doc/developer/process-architecture.rst +++ b/doc/developer/process-architecture.rst @@ -28,7 +28,7 @@ within the event system are variations on the term "thread". The primary datastructure that holds the state of an event loop in this system is called a "threadmaster". Events scheduled on the event loop - what would today be called an 'event' or 'task' in systems such as libevent - are called "threads" and the -datastructure for them is ``struct thread``. To add to the confusion, these +datastructure for them is ``struct event``. To add to the confusion, these "threads" have various types, one of which is "event". To hopefully avoid some of this confusion, this document refers to these "threads" as a 'task' except where the datastructures are explicitly named. When they are explicitly named, @@ -47,7 +47,7 @@ section. For now it provides basic information necessary to understand the interplay between the event system and kernel threads. The core event system is implemented in :file:`lib/thread.[ch]`. The primary -structure is ``struct thread_master``, hereafter referred to as a +structure is ``struct event_loop``, hereafter referred to as a ``threadmaster``. A ``threadmaster`` is a global state object, or context, that holds all the tasks currently pending execution as well as statistics on tasks that have already executed. The event system is driven by adding tasks to this @@ -57,7 +57,7 @@ execute. At initialization, a daemon will typically create one fetch each task and execute it. These tasks have various types corresponding to their general action. The types -are given by integer macros in :file:`thread.h` and are: +are given by integer macros in :file:`event.h` and are: ``THREAD_READ`` Task which waits for a file descriptor to become ready for reading and then @@ -80,8 +80,8 @@ are given by integer macros in :file:`thread.h` and are: Type used internally for tasks on the ready queue. ``THREAD_UNUSED`` - Type used internally for ``struct thread`` objects that aren't being used. - The event system pools ``struct thread`` to avoid heap allocations; this is + Type used internally for ``struct event`` objects that aren't being used. + The event system pools ``struct event`` to avoid heap allocations; this is the type they have when they're in the pool. ``THREAD_EXECUTE`` @@ -95,9 +95,9 @@ irrelevant for the time being) for the specific type. For example, to add a :: - thread_add_read(struct thread_master *master, int (*handler)(struct thread *), void *arg, int fd, struct thread **ref); + event_add_read(struct event_loop *master, int (*handler)(struct event *), void *arg, int fd, struct event **ref); -The ``struct thread`` is then created and added to the appropriate internal +The ``struct event`` is then created and added to the appropriate internal datastructure within the ``threadmaster``. Note that the ``READ`` and ``WRITE`` tasks are independent - a ``READ`` task only tests for readability, for example. @@ -111,13 +111,13 @@ program. When no more tasks are available, the program dies. Typically at startup the first task added is an I/O task for VTYSH as well as any network sockets needed for peerings or IPC. -To retrieve the next task to run the program calls ``thread_fetch()``. -``thread_fetch()`` internally computes which task to execute next based on +To retrieve the next task to run the program calls ``event_fetch()``. +``event_fetch()`` internally computes which task to execute next based on rudimentary priority logic. Events (type ``THREAD_EVENT``) execute with the highest priority, followed by expired timers and finally I/O tasks (type ``THREAD_READ`` and ``THREAD_WRITE``). When scheduling a task a function and an -arbitrary argument are provided. The task returned from ``thread_fetch()`` is -then executed with ``thread_call()``. +arbitrary argument are provided. The task returned from ``event_fetch()`` is +then executed with ``event_call()``. The following diagram illustrates a simplified version of this infrastructure. @@ -133,18 +133,18 @@ illustrated at the bottom. Mapping the general names used in the figure to specific FRR functions: -- ``task`` is ``struct thread *`` -- ``fetch`` is ``thread_fetch()`` -- ``exec()`` is ``thread_call`` -- ``cancel()`` is ``thread_cancel()`` -- ``schedule()`` is any of the various task-specific ``thread_add_*`` functions +- ``task`` is ``struct event *`` +- ``fetch`` is ``event_fetch()`` +- ``exec()`` is ``event_call`` +- ``cancel()`` is ``event_cancel()`` +- ``schedule()`` is any of the various task-specific ``event_add_*`` functions Adding tasks is done with various task-specific function-like macros. These macros wrap underlying functions in :file:`thread.c` to provide additional information added at compile time, such as the line number the task was scheduled from, that can be accessed at runtime for debugging, logging and informational purposes. Each task type has its own specific scheduling function -that follow the naming convention ``thread_add_<type>``; see :file:`thread.h` +that follow the naming convention ``event_add_<type>``; see :file:`event.h` for details. There are some gotchas to keep in mind: @@ -228,7 +228,7 @@ well as *any other pthread*. This serves as the basis for inter-thread communication and boils down to a slightly more complicated method of message passing, where the messages are the regular task events as used in the event-driven model. The only difference is thread cancellation, which requires -calling ``thread_cancel_async()`` instead of ``thread_cancel`` to cancel a task +calling ``event_cancel_async()`` instead of ``event_cancel`` to cancel a task currently scheduled on a ``threadmaster`` belonging to a different pthread. This is necessary to avoid race conditions in the specific case where one pthread wants to guarantee that a task on another pthread is cancelled before diff --git a/doc/developer/rcu.rst b/doc/developer/rcu.rst index ac4405121e..4fd56587ae 100644 --- a/doc/developer/rcu.rst +++ b/doc/developer/rcu.rst @@ -120,7 +120,7 @@ atomic ops & datastructures with other types of locking, e.g. rwlocks. The ``thread_master`` code currently always holds RCU everywhere, except while doing the actual ``poll()`` syscall. This is both an optimization as well as an "easement" into getting RCU going. The current implementation - contract is that any ``struct thread *`` callback is called with a RCU + contract is that any ``struct event *`` callback is called with a RCU holding depth of 1, and that this is owned by the thread so it may (should) drop and reacquire it when doing some longer-running work. diff --git a/doc/developer/tracing.rst b/doc/developer/tracing.rst index 63b04585f1..76f6004034 100644 --- a/doc/developer/tracing.rst +++ b/doc/developer/tracing.rst @@ -150,8 +150,8 @@ Example:: frr_libfrr:frr_pthread_stop (loglevel: TRACE_DEBUG_LINE (13)) (type: tracepoint) frr_libfrr:frr_pthread_run (loglevel: TRACE_DEBUG_LINE (13)) (type: tracepoint) frr_libfrr:thread_call (loglevel: TRACE_INFO (6)) (type: tracepoint) - frr_libfrr:thread_cancel_async (loglevel: TRACE_INFO (6)) (type: tracepoint) - frr_libfrr:thread_cancel (loglevel: TRACE_INFO (6)) (type: tracepoint) + frr_libfrr:event_cancel_async (loglevel: TRACE_INFO (6)) (type: tracepoint) + frr_libfrr:event_cancel (loglevel: TRACE_INFO (6)) (type: tracepoint) frr_libfrr:schedule_write (loglevel: TRACE_INFO (6)) (type: tracepoint) frr_libfrr:schedule_read (loglevel: TRACE_INFO (6)) (type: tracepoint) frr_libfrr:schedule_event (loglevel: TRACE_INFO (6)) (type: tracepoint) |