From d2292c6bfee5f3e82e236bf679a9ed0980032f17 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 27 Sep 2023 19:53:10 -0400 Subject: [PATCH 1/2] doc: fix whitespace, formatting errors * Fix various whitespace and syntax errors * Fix a couple tiny grammar mistakes Signed-off-by: Quentin Young --- doc/developer/building-frr-for-ubuntu2204.rst | 1 + doc/developer/cli.rst | 34 ++-- doc/developer/cspf.rst | 162 +++++++++--------- doc/developer/topotests.rst | 6 +- doc/developer/workflow.rst | 1 + 5 files changed, 105 insertions(+), 99 deletions(-) diff --git a/doc/developer/building-frr-for-ubuntu2204.rst b/doc/developer/building-frr-for-ubuntu2204.rst index 7e62d85763e7..97bdf8806bef 100644 --- a/doc/developer/building-frr-for-ubuntu2204.rst +++ b/doc/developer/building-frr-for-ubuntu2204.rst @@ -58,6 +58,7 @@ If config rollbacks are enabled using ``--enable-config-rollbacks`` the sqlite3 developer package also should be installed. .. code-block:: console + sudo apt install libsqlite3-dev diff --git a/doc/developer/cli.rst b/doc/developer/cli.rst index 61b9cf6acb53..59073b39ab44 100644 --- a/doc/developer/cli.rst +++ b/doc/developer/cli.rst @@ -639,13 +639,14 @@ in order into ``*argv[]``. Before this happens the ``->arg`` field is set to point at the snippet of user input that matched it. For most nontrivial commands the handler function will need to determine which -of the possible matching inputs was entered. Previously this was done by looking -at the first few characters of input. This is now considered an anti-pattern and -should be avoided. Instead, the ``->type`` or ``->text`` fields for this logic. -The ``->type`` field can be used when the possible inputs differ in type. When -the possible types are the same, use the ``->text`` field. This field has the -full text of the corresponding token in the definition string and using it makes -for much more readable code. An example is helpful. +of the possible matching inputs was entered. Previously this was done by +looking at the first few characters of input. This is now considered an +anti-pattern and should be avoided. Instead, use the ``->type`` or ``->text`` +fields for this logic. The ``->type`` field can be used when the possible +inputs differ in type. When the possible types are the same, use the ``->text`` +field. This field has the full text of the corresponding token in the +definition string and using it makes for much more readable code. An example is +helpful. Command definition: @@ -654,9 +655,10 @@ Command definition: command <(1-10)|foo|BAR> In this example, the user may enter any one of: -- an integer between 1 and 10 -- "foo" -- anything at all + +* an integer between 1 and 10 +* "foo" +* anything at all If the user enters "command f", then: @@ -793,12 +795,12 @@ Adding a CLI Node To add a new CLI node, you should: -- define a new numerical node constant -- define a node structure in the relevant daemon -- call ``install_node()`` in the relevant daemon -- define and install the new node in vtysh -- define corresponding node entry commands in daemon and vtysh -- add a new entry to the ``ctx_keywords`` dictionary in ``tools/frr-reload.py`` +#. define a new numerical node constant +#. define a node structure in the relevant daemon +#. call ``install_node()`` in the relevant daemon +#. define and install the new node in vtysh +#. define corresponding node entry commands in daemon and vtysh +#. add a new entry to the ``ctx_keywords`` dictionary in ``tools/frr-reload.py`` Defining the numerical node constant ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/developer/cspf.rst b/doc/developer/cspf.rst index 9ff673a23944..7a5a55ee31b0 100644 --- a/doc/developer/cspf.rst +++ b/doc/developer/cspf.rst @@ -24,59 +24,59 @@ to the cost of the cuurent path from the source up to the current node. The algorithm is as followed: -``` - cost = MAX_COST; - Priority_Queue.empty(); - Visited_Node.empty(); - Processed_Path.empty(); - src = new_path(source_address); - src.cost = 0; - dst = new_destinatio(destination_address); - dst.cost = MAX_COST; - Processed_Path.add(src); - Processed_Path.add(dst); - while (Priority_Queue.count != 0) { - current_path = Priority_Queue.pop(); - current_node = next_path.destination; - Visited_Node.add(current_node); - for (current_node.edges: edge) { - if (prune_edge(current_path, edge) - continue; - if (relax(current_path) && cost > current_path.cost) { - optim_path = current_path; - cost = current_path.cost; - } - } - } - - prune_edge(path, edge) { - // check that path + edge meet constraints e.g. - if (current_path.cost + edge.cost > constrained_cost) - return false; - else - return true; - } - - relax_edge(current_path, edge) { - next_node = edge.destination; - if (Visited_Node.get(next_node)) - return false; - next_path = Processed_Path.get(edge.destination); - if (!next_path) { - next_path = new path(edge.destination); - Processed_Path.add(next_path); - } - total_cost = current_path.cost + edge.cost; - if (total_cost < next_path.cost) { - next_path = current_path; - next_path.add_edge(edge); - next_path.cost = total_cost; - Priority_Queue.add(next_path); - } - return (next_path.destination == destination); - } - -``` +.. code-block:: c + + cost = MAX_COST; + Priority_Queue.empty(); + Visited_Node.empty(); + Processed_Path.empty(); + src = new_path(source_address); + src.cost = 0; + dst = new_destinatio(destination_address); + dst.cost = MAX_COST; + Processed_Path.add(src); + Processed_Path.add(dst); + while (Priority_Queue.count != 0) { + current_path = Priority_Queue.pop(); + current_node = next_path.destination; + Visited_Node.add(current_node); + for (current_node.edges: edge) { + if (prune_edge(current_path, edge) + continue; + if (relax(current_path) && cost > current_path.cost) { + optim_path = current_path; + cost = current_path.cost; + } + } + } + + prune_edge(path, edge) { + // check that path + edge meet constraints e.g. + if (current_path.cost + edge.cost > constrained_cost) + return false; + else + return true; + } + + relax_edge(current_path, edge) { + next_node = edge.destination; + if (Visited_Node.get(next_node)) + return false; + next_path = Processed_Path.get(edge.destination); + if (!next_path) { + next_path = new path(edge.destination); + Processed_Path.add(next_path); + } + total_cost = current_path.cost + edge.cost; + if (total_cost < next_path.cost) { + next_path = current_path; + next_path.add_edge(edge); + next_path.cost = total_cost; + Priority_Queue.add(next_path); + } + return (next_path.destination == destination); + } + Definition ---------- @@ -163,34 +163,34 @@ To perform a Path Computation with given constraints, proceed as follow: .. code-block:: c - struct cspf *algo; - struct ls_ted *ted; - struct in_addr src; - struct in_addr dst; - struct constraints csts; - struct c_path *path; - - // Create a new CSPF structure - algo = cspf_new(); - - // Initialize constraints - csts.cost = 100; - csts.ctype = CSPF_TE_METRIC; - csts.family = AF_INET; - csts.type = SR_TE; - csts.bw = 1000000; - csts.cos = 3; - - // Then, initialise th CSPF with source, destination and constraints - cspf_init_v4(algo, ted, src, dst, &csts); - - // Finally, got the Computed Path; - path = compute_p2p_path(ted, algo); - - if (path.status == SUCCESS) - zlog_info("Got a valid constraints path"); - else - zlog_info("Unable to compute constraints path. Got %d status", path->status); + struct cspf *algo; + struct ls_ted *ted; + struct in_addr src; + struct in_addr dst; + struct constraints csts; + struct c_path *path; + + // Create a new CSPF structure + algo = cspf_new(); + + // Initialize constraints + csts.cost = 100; + csts.ctype = CSPF_TE_METRIC; + csts.family = AF_INET; + csts.type = SR_TE; + csts.bw = 1000000; + csts.cos = 3; + + // Then, initialise th CSPF with source, destination and constraints + cspf_init_v4(algo, ted, src, dst, &csts); + + // Finally, got the Computed Path; + path = compute_p2p_path(ted, algo); + + if (path.status == SUCCESS) + zlog_info("Got a valid constraints path"); + else + zlog_info("Unable to compute constraints path. Got %d status", path->status); If you would compute another path, you must call `cspf_init()` prior to diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index 87edad40bb58..0e4f05ed0041 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -472,8 +472,8 @@ For each capture a window is opened displaying a live summary of the captured packets. Additionally, the entire packet stream is captured in a pcap file in the tests log directory e.g.,:: -When using a unified log file `frr.log` one substitutes `frr` for the daemon -name in the ``--logd`` CLI option, e.g., +When using a unified log file ``frr.log`` one substitutes ``frr`` for the +daemon name in the ``--logd`` CLI option, e.g., .. code:: shell @@ -617,6 +617,8 @@ allocations upon exit. To enable also reporting of memory leaks to a specific location, define an environment variable ``TOPOTESTS_CHECK_MEMLEAK`` with the file prefix, i.e.: +:: + export TOPOTESTS_CHECK_MEMLEAK="/home/mydir/memleak_" For tests that support the TOPOTESTS_CHECK_MEMLEAK environment variable, this diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 72d2a49376a6..e26486efdec5 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -817,6 +817,7 @@ The project provides multiple tools to allow you to correctly style your code as painlessly as possible, primarily built around ``clang-format``. clang-format + In the project root there is a :file:`.clang-format` configuration file which can be used with the ``clang-format`` source formatter tool from the LLVM project. Most of the time, this is the easiest and smartest tool to From e45651fbd0681244be1dd98834657c1e38e60e8b Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 27 Sep 2023 19:54:02 -0400 Subject: [PATCH 2/2] doc: include checkpatch & cspf docs in toctree The documentation pages on checkpatch and CSPF were not reachable because they were not included in any toctree. Include them in the tree! Signed-off-by: Quentin Young --- doc/developer/checkpatch.rst | 2 ++ doc/developer/index.rst | 1 + doc/developer/ospf.rst | 1 + doc/developer/workflow.rst | 2 ++ 4 files changed, 6 insertions(+) diff --git a/doc/developer/checkpatch.rst b/doc/developer/checkpatch.rst index b52452bc2963..d8fe007c3131 100644 --- a/doc/developer/checkpatch.rst +++ b/doc/developer/checkpatch.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0-only +.. _checkpatch: + ========== Checkpatch ========== diff --git a/doc/developer/index.rst b/doc/developer/index.rst index c2123f1ad209..bd794b11a8df 100644 --- a/doc/developer/index.rst +++ b/doc/developer/index.rst @@ -5,6 +5,7 @@ FRRouting Developer's Guide :maxdepth: 2 workflow + checkpatch building packaging process-architecture diff --git a/doc/developer/ospf.rst b/doc/developer/ospf.rst index a5164d552a18..837a0bd18598 100644 --- a/doc/developer/ospf.rst +++ b/doc/developer/ospf.rst @@ -9,4 +9,5 @@ OSPFD ospf-api ospf-sr + cspf diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index e26486efdec5..68834ed71096 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -876,6 +876,8 @@ clang-format checkpatch.sh checkpatch.pl + .. seealso:: :ref:`checkpatch` + In the Linux kernel source tree there is a Perl script used to check incoming patches for style errors. FRR uses a shell script front end and an adapted version of the perl script for the same purpose. These scripts can