Re: [PATCH] doc: reword glossary

[Stephen Hemminger <stephen@networkplumber.org>]

On Thu, 21 Nov 2024 18:26:45 -0800
Nandini Persad <nandinipersad361@gmail.com> wrote:

> I added additional reference links and definitions to many
> of the terms in the glossary. Please feel free to provide
> feedback to ensure my definitions suit the proper context
> in the DPDK community.
> 
> Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>

Rather than putting links after the text, they can be embedded
which solves lots of the reference warnings.

Please only link to neutral third party places like IETF (RFC's), Wikipedia, etc.
Not vendor sites.

I added a few more links, and there are many more that could go here.
HPET, IPv4 (RFC), IPv6 (RFC), LAN (wikipedia), MTU, NIC, Out of Order execution,
PCI (PCI standard), PHY (wikipedia), PIE (RFC), QoS (various RFC's),
RCU (wikipedia), RED(RFC), RSS (wikipedia) , SLA, srTCM, Traffic Class,
TLB, TSC, TUN/TAP, VLAN, WRED, ...

diff --git a/doc/guides/prog_guide/glossary.rst b/doc/guides/prog_guide/glossary.rst
index 9f85e46437..d832d4c0be 100644
--- a/doc/guides/prog_guide/glossary.rst
+++ b/doc/guides/prog_guide/glossary.rst
@@ -6,35 +6,35 @@ Glossary
 
 
 ACL
-   An access control list (ACL) is a set of rules that define who can access a resource and what actions they can perform.
-   `ACL Link <https://www.fortinet.com/resources/cyberglossary/network-access-control-list#:~:text=A%20network%20access%20control%20list%20(ACL)%20is%20made%20up%20of,device%2C%20it%20cannot%20gain%20access.>`_
+   An `access control list (ACL) <https://en.wikipedia.org/wiki/Access-control_list>`_
+   is a set of rules that define who can access a resource and what actions they can perform.
 
 API
    Application Programming Interface
 
 ASLR
-   Linux* kernel Address-Space Layout Randomization
-   A computer security technique that protects against buffer overflow attacks by randomizing the location of executables in memory in Linux.
-   `ASLR Link <https://en.wikipedia.org/wiki/Address_space_layout_randomization>`_
+   `Address-Space Layout Randomization (ASLR) <https://en.wikipedia.org/wiki/Address_space_layout_randomization>`_
+   is a computer security technique that protects against buffer overflow attacks by randomizing the location of
+   executables in memory.
 
 BSD
-   Berkeley Software Distribution is a Unix-like operating system.
+   `Berkeley Software Distribution (BSD) <https://en.wikipedia.org/wiki/Berkeley_Software_Distribution>`_
+   is an version of Unix™ operating system.
 
 Clr
    Clear
 
 CIDR
-   Classless Inter-Domain Routing
-   A method of assigning IP address that improves data routing efficiency on the internet and is used in IPv4 and IPv6.
-   `RFC Link <https://datatracker.ietf.org/doc/html/rfc1918>`_
+   `Classless Inter-Domain Routing (CIDR) <https://datatracker.ietf.org/doc/html/rfc1918>`_
+   is a method of assigning IP address that improves data routing efficiency on the internet and is used in IPv4 and IPv6.
 
 Control Plane
-   A Control Plane is a key concept in networking that refers to the part of a network system
+   A `Control Plane <https://en.wikipedia.org/wiki/Control_plane>`_ is a concept in networking that refers to the part of the system
    responsible for managing and making decisions about where and how data packets are forwarded within a network.
 
 Core
-   A core may include several lcores or threads if the processor supports simultaneous multithreading (SMT).
-   `Simultaneous Multithreading <https://en.wikipedia.org/wiki/Simultaneous_multithreading>`_
+   A core may include several lcores or threads if the processor supports
+   `simultaneous multithreading (SMT) <https://en.wikipedia.org/wiki/Simultaneous_multithreading>`_
 
 Core Components
    A set of libraries provided by DPDK which are used by nearly all applications and
@@ -49,8 +49,9 @@ CRC
 
 Data Plane
    In contrast to the control plane, which is responsible for setting up and managing data connections,
-   the data plane in a network architecture includes the layers involved when processing and forwarding
-   data packets between communicating endpoints. These layers must be highly optimized to achieve good performance.
+   the `data plane <https://en.wikipedia.org/wiki/Data_plane>`_ in a network architecture includes the
+   layers involved when processing and forwarding data packets between communicating endpoints.
+   These layers must be highly optimized to achieve good performance.
 
 DIMM
    Dual In-line Memory Module
@@ -58,23 +59,22 @@ DIMM
    circuit board that connect it directly to the computer motherboard.
 
 Doxygen
-   A documentation generator used in the DPDK to generate the API reference.
-   `Doxygen Link <https://www.doxygen.nl/>`_
+   `Doxygen <https://www.doxygen.nl/>`_ is a
+   documentation generator used in the DPDK to generate the API reference.
 
 DPDK
    Data Plane Development Kit
 
 DRAM
-   Dynamic Random Access Memory
-   A type of random access memory (RAM) that is used in computers to temporarily store information.
-   `Link <https://en.wikipedia.org/wiki/Dynamic_random-access_memory>`_
+   `Dynamic Random Access Memory <https://en.wikipedia.org/wiki/Dynamic_random-access_memory>`_
+   is  type of random access memory (RAM) that is used in computers to temporarily store information.
 
 EAL
-   The Environment Abstraction Layer (EAL) is a DPDK core library that provides a generic interface
-   that hides the environment specifics from the applications and libraries. The services expected
-   from the EAL are: development kit loading and launching, core affinity/ assignment procedures, system
-   memory allocation/description, PCI bus access, inter-partition communication.
-   `Link <https://github.com/emmericp/dpdk-github-inofficial/blob/master/doc/guides/prog_guide/env_abstraction_layer.rst>`_
+   :doc:`Environment Abstraction Layer (EAL) <env_abstraction_layer>`
+   is a the core DPDK library that provides a generic interface
+   that hides the environment specifics from the applications and libraries.
+   The services expected from the EAL are: loading and launching, core management,
+   memory allocation, bus management, and inter-partition communication.
 
 EAL Thread
    An EAL thread is typically a thread that runs packet processing tasks. These threads are often
@@ -83,15 +83,13 @@ EAL Thread
    EAL threads can also handle other tasks like managing buffers, queues, and I/O operations.
 
 FIFO
-   First In First Out
-   A method for organizing the manipulation of a data structure where the oldest (first) entry, or
+   `First In First Out (FIFO) <https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)>`_
+   is a method for organizing the manipulation of a data structure where the oldest (first) entry, or
    "head" of the queue, is processed first.
-   `Link <https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)>`_
 
 FPGA
-   Field Programmable Gate Array
+   `Field Programmable Gate Array (FPGA) <https://en.wikipedia.org/wiki/Field-programmable_gate_array>`_
    An integrated circuit with a programmable hardware fabric that can be reconfigured to suit different purposes.
-   `Link <https://en.wikipedia.org/wiki/Field-programmable_gate_array>`_
 
 GbE
    Gigabit Ethernet
@@ -104,12 +102,12 @@ HPET
    reference on x86 platforms.
 
 Huge Pages
-   Memory page sizes, larger than the default page size, which are supported by the host CPU.
+   `Huge pages <https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html>`_
+   are memory page sizes, larger than the default page size, which are supported by the host CPU.
    These pages are generally megabytes or even a gigabytes in size,  depending on platform,
    compared to the default page size on most platforms which is measured in kilobytes, e.g. 4k.
    Where the operating system provides access to hugepage memory, DPDK will take advantage of
    those hugepages for increased performance.
-   `Link <https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html>`_
 
 ID
    Identifier
@@ -135,31 +133,29 @@ lcore
    Also known as logical core.
 
 L1
-   Layer 1
+   Layer 1 - `Physical Layer <https://en.wikipedia.org/wiki/Physical_layer>`_
    The Physical layer of the network responsible for sending and receiving signals to transmit data.
 
 L2
-   Layer 2
+   Layer 2 - `Datalink Layer <https://en.wikipedia.org/wiki/Data_link_layer>`_
 
 L3
-   Layer 3
+   Layer 3 - `Network Layer <https://en.wikipedia.org/wiki/Network_layer>`_
    Also known as the network layer, Layer 3 is responsible for packet forwarding including routing through intermediate routers
    Example protocols include IP v4 and IP v6.
-   `Network Layer <https://en.wikipedia.org/wiki/Network_layer>`_
 
 L4
-   Layer 4
+   Layer 4 - `Transport Layer <https://en.wikipedia.org/wiki/Transport_layer>`_
    Examples include UDP and TCP.
-   `Transport Layer <https://en.wikipedia.org/wiki/Transport_layer>`_
+
 
 LAN
    Local Area Network
 
 LPM
-   Longest Prefix Match
-   A table lookup algorithm where the entry selected is that which matches the longest initial part (or prefix)
+   `Longest Prefix Match <https://en.wikipedia.org/wiki/Longest_prefix_match>`_ is
+   a lookup algorithm where the entry selected is that which matches the longest initial part (or prefix)
    of the lookup key, rather than requiring an exact match on the full key.
-   `Reference Link <https://en.wikipedia.org/wiki/Longest_prefix_match>`_
 
 main lcore
    The logical core or thread that executes the main function and that launches tasks on other logical
@@ -186,9 +182,8 @@ OOO
    Out Of Order (execution of instructions within the CPU pipeline)
 
 NUMA
-   Non-uniform Memory Access
+   `Non-uniform Memory Access (NUMA) <https://en.wikipedia.org/wiki/Non-uniform_memory_access>`_
    A computer memory design that allows processors to access memory faster when it's located closer to them.
-   `Reference Link <https://en.wikipedia.org/wiki/Non-uniform_memory_access>`_
 
 PCI
    Peripheral Connect Interface
@@ -267,15 +262,13 @@ TLB
    A memory cache that stores the recent translations of virtual memory to physical memory to enable faster retrieval.
 
 TLS
-   Thread Local Storage
+   `Thread Local Storage <https://en.wikipedia.org/wiki/Thread-local_storage>`_
    A memory management method that uses static or global memory local to a thread.
-   `Reference Link <https://en.wikipedia.org/wiki/Thread-local_storage>`_
 
 trTCM
-   Two Rate Three Color Marking
+   `Two Rate Three Color Marking <https://datatracker.ietf.org/doc/html/rfc2698>`
    A component that meters an IP traffic stream, marks it as one of three color category
    sand assists in traffic congestion-control.
-   `RFC Link <https://datatracker.ietf.org/doc/html/rfc2698>`_
 
 TSC
    Time Stamp Counter