Merge pull request #6693 from qlyoung/doc-value-initialization-practices

Document value initialization practices

doc/developer/lua.rst

@@ -53,7 +53,7 @@ follow these steps:
          zlog_debug(string.format("afi: %d: %s %d ifdx: %d aspath: %s localpref: %d",
                     prefix.family, prefix.route, nexthop.metric,
                     nexthop.ifindex, nexthop.aspath, nexthop.localpref))
-    
+
          nexthop.metric =  33
          nexthop.localpref = 13
          return 3

doc/developer/workflow.rst

@@ -276,7 +276,7 @@ Pre-submission Checklist
 - In the case of a major new feature or other significant change, document
   plans for continued maintenance of the feature.  In addition it is a
   requirement that automated testing must be written that exercises
-  the new feature within our existing CI infrastructure.  Also the 
+  the new feature within our existing CI infrastructure.  Also the
   addition of automated testing to cover any pull request is encouraged.
 
 .. _signing-off:
@@ -573,6 +573,30 @@ following requirements have achieved consensus:
   constant in these cases.  (Rationale:  changing a buffer to another size
   constant may leave the write operations on a now-incorrect size limit.)
 
+- For stack allocated structs and arrays that should be zero initialized,
+  prefer initializer expressions over ``memset()`` wherever possible. This
+  helps prevent ``memset()`` calls being missed in branches, and eliminates the
+  error class of an incorrect ``size`` argument to ``memset()``.
+
+  For example, instead of:
+
+  .. code-block:: c
+
+     struct foo mystruct;
+     ...
+     memset(&mystruct, 0x00, sizeof(struct foo));
+
+  Prefer:
+
+  .. code-block:: c
+
+     struct foo mystruct = {};
+
+- Do not zero initialize stack allocated values that must be initialized with a
+  nonzero value in order to be used. This way the compiler and memory checking
+  tools can catch uninitialized value use that would otherwise be suppressed by
+  the (incorrect) zero initialization.
+
 Other than these specific rules, coding practices from the Linux kernel as
 well as CERT or MISRA C guidelines may provide useful input on safe C code.
 However, these rules are not applied as-is;  some of them expressly collide

doc/user/bfd.rst

@@ -473,7 +473,7 @@ You can inspect the current BFD peer status in brief with the following commands
 
 ::
 
-   frr# show bfd peers brief 
+   frr# show bfd peers brief
    Session count: 1
    SessionId  LocalAddress         PeerAddress      Status
    =========  ============         ===========      ======

doc/user/overview.rst

@@ -402,7 +402,7 @@ VRRP
   :t:`Virtual Router Redundancy Protocol (VRRP). R. Hinden. April 2004.`
 - :rfc:`5798`
   :t:`Virtual Router Redundancy Protocol (VRRP) Version 3 for IPv4 and IPv6. S. Nadas. June 2000.`
-  
+
 SNMP
 ----
 

doc/user/pim.rst

@@ -185,7 +185,7 @@ Certain signals have special meanings to *pimd*.
    warning once the configured group limit is reached while adding new groups.
    'no' form of the command disables the warning generation. This command is
    vrf aware. To configure per vrf, enter vrf submode.
-   
+
 .. _pim-interface-configuration:
 
 PIM Interface Configuration

doc/user/setup.rst

@@ -220,7 +220,7 @@ individual or unified daemon configuration files.
 
 See :ref:`FRR-RELOAD <frr-reload>` for more about the `frr-reload.py` script.
 
-      
+
 Starting a new daemon
 ^^^^^^^^^^^^^^^^^^^^^
 

doc/user/wecmp_linkbw.rst

@@ -250,8 +250,8 @@ attribute from two peers is shown below:
        (fe80::202:ff:fe00:1b) (used)
          Origin IGP, metric 0, valid, external, multipath, bestpath-from-AS 65002
          Extended Community: LB:65002:125000000 (1000.000 Mbps)
-         Last update: Thu Feb 20 18:34:16 2020  
+         Last update: Thu Feb 20 18:34:16 2020
-   
+
      65001
        fe80::202:ff:fe00:15 from l1(swp1) (110.0.0.1)
        (fe80::202:ff:fe00:15) (used)

doc/user/zebra.rst

@@ -663,7 +663,7 @@ kernel.
 .. clicmd:: ip protocol PROTOCOL route-map ROUTEMAP
 
    Apply a route-map filter to routes for the specified protocol. PROTOCOL can
-   be: 
+   be:
 
    - any,
    - babel,