git: a6e9e4cb259c - main - nhop.9: Rewrite relics of rtentry.9 into nhop.9

The branch main has been updated by pouria:

URL: https://cgit.FreeBSD.org/src/commit/?id=a6e9e4cb259c3394aab4dc3e407d932866a02884

commit a6e9e4cb259c3394aab4dc3e407d932866a02884
Author:     Pouria Mousavizadeh Tehrani <[email protected]>
AuthorDate: 2026-08-19 17:40:38 +0000
Commit:     Pouria Mousavizadeh Tehrani <[email protected]>
CommitDate: 2026-08-19 18:16:03 +0000

    nhop.9: Rewrite relics of rtentry.9 into nhop.9
    
    Parts of rtentry.9 information such as information related to
    the nexthop is outdated.
    Remove those relics and add the new design into separate
    manual instead.
    
    Reviewed by:    bcr
    Discussed with: ziaee
    Differential Revision: https://reviews.freebsd.org/D58564
---
 share/man/man9/Makefile  |   2 +
 share/man/man9/nhop.9    | 123 +++++++++++++++++++++++++++++++++++++++++++++++
 share/man/man9/rtentry.9 |  56 ++++++---------------
 3 files changed, 141 insertions(+), 40 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 1deb3d048f12..54a121faca0f 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -245,6 +245,7 @@ MAN=	accept_filter.9 \
 	mutex.9 \
 	namei.9 \
 	netisr.9 \
+	nhop.9 \
 	nv.9 \
 	nvmem.9 \
 	OF_child.9 \
@@ -1680,6 +1681,7 @@ MLINKS+=netisr.9 netisr_clearqdrops.9 \
 	netisr.9 netisr_register.9 \
 	netisr.9 netisr_setqlimit.9 \
 	netisr.9 netisr_unregister.9
+MLINKS+=nhop.9 nhop_object.9
 MLINKS+=nv.9 libnv.9 \
 	nv.9 nvlist.9 \
 	nv.9 nvlist_add_binary.9 \
diff --git a/share/man/man9/nhop.9 b/share/man/man9/nhop.9
new file mode 100644
index 000000000000..58f50e53a315
--- /dev/null
+++ b/share/man/man9/nhop.9
@@ -0,0 +1,123 @@
+.\"
+.\" Copyright (c) 2026 Pouria Mousavizadeh Tehrani <[email protected]>
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.Dd July 30, 2026
+.Dt NHOP 9
+.Os
+.Sh NAME
+.Nm nhop ,
+.Nm nhop_object
+.Nd structure of a nexthop entry in the kernel routing table
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/socket.h
+.In net/route.h
+.In net/route/nhop.h
+.Sh DESCRIPTION
+The kernel provides a common mechanism by which all routes can store
+and retrieve nexthop entries from a central table of routes.
+The
+.In net/route/nhop.h
+header file defines the structures and manifest constants used in this
+facility.
+.Pp
+The data plane structure of a nexthop is defined by
+.Vt "struct nhop_object" ,
+which includes the following fields:
+.Bl -tag -offset indent -width 6n
+.It Vt "uint16_t flags" ;
+See below.
+.It Vt "uint16_t nh_mtu" ;
+MTU for this nexthop.
+.It Vt "char gw_buf[28]";
+The gateway of the nexthop.
+An storage suitable to hold AF_INET, AF_INET6, or AF_NET gateway.
+.It Vt "struct ifnet *nh_ifp" ;
+.It Vt "struct ifaddr *nh_ifa" ;
+These two fields represent the
+.Dq answer ,
+as it were, to the question posed by a route lookup; that is, they
+name the interface and interface address to be used in sending a
+packet to the destination or set of destinations which nexthop represents.
+.It Vt "struct ifnet *nh_aifp" ;
+Interface of the source address.
+It is same as
+.Va nh_ifp
+except for IPv6 loopback routes, or when the
+.Dv NHF_PREFSRC
+is set, which means the source address is borrowed from another interface.
+.It Vt "counter_u64_t nh_pksent";
+A count of packets successfully sent via this nexthop.
+.It Vt "uint8_t nh_prepend_len";
+link-level prepend length which is currently unused.
+.It Vt "uint8_t spare[3]";
+.It Vt "uint32_t spare1";
+These two fields are unused.
+.It Vt "char nh_prepend[48]";
+link-level prepend data which is currently unused.
+.It Vt "struct nhop_priv *nh_priv";
+Pointer to control plane data of nexthop.
+.El
+.Pp
+The following flag bits are defined:
+.Bl -tag -offset indent -width "NHF_BLACKHOLE" -compact
+.It Dv NHF_MULTIPATH
+The nexthop is a nexthop group.
+.It Dv NHF_REJECT
+Same as
+.Dv RTF_REJECT .
+The destination is presently unreachable.
+.It Dv NHF_BLACKHOLE
+Same as
+.Dv RTF_BLACKHOLE
+Requests that output sent via this nexthop be discarded.
+.It Dv NHF_REDIRECT
+Same as
+.Dv RTF_DYNAMIC
+and
+.Dv RTF_MODIFIED
+flags together.
+.It Dv NHF_DEFAULT
+The nexthop is used for default route.
+.It Dv NHF_BROADCAST
+Same as
+.Dv RTF_BROADCAST
+Indicates that the destination is a broadcast address.
+.It Dv NHF_GATEWAY
+Same as
+.Dv RTF_GATEWAY
+The route points to an intermediate destination and not the ultimate
+recipient; the
+.Va gw4_sa
+and
+.Va gw6_sa
+fields name that destination.
+.It Dv NHF_HOST
+Same as
+.Dv RTF_HOST
+This is a nexthop to a host route.
+This should result in an
+.Er EHOSTUNREACH
+error from output routines.
+.It Dv NHF_INVALID
+This nexthop is currently down.
+.It Dv NHF_PREFSRC
+Used only in the
+.Xr rtnetlink 4
+indicating that the source address is manually overwritten.
+.El
+.Sh SEE ALSO
+.Xr route 4 ,
+.Xr route 8 ,
+.Xr rtentry 9
+.Sh HISTORY
+The
+.Nm
+stack is a rework of routing subsystem by
+.An Alexander V. Chernikov Aq [email protected]
+.Sh AUTHORS
+.An -nosplit
+This manual page was written by
+.An Seyed Pouria Mousavizadeh Tehrani Aq [email protected]
diff --git a/share/man/man9/rtentry.9 b/share/man/man9/rtentry.9
index 3f2e6c9ef656..50eff5bfc14c 100644
--- a/share/man/man9/rtentry.9
+++ b/share/man/man9/rtentry.9
@@ -26,7 +26,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 5, 2014
+.Dd July 30, 2026
 .Dt RTENTRY 9
 .Os
 .Sh NAME
@@ -66,12 +66,13 @@ macros can be used to extract this information (in the form of a
 .Vt "struct sockaddr *" )
 given a
 .Vt "struct rtentry *" .
-.It Vt "struct sockaddr *rt_gateway" ;
+.It Vt "struct nhop_object *rt_nhop" ;
 The
-.Dq target
-of the route, which can either represent a destination in its own
-right (some protocols will put a link-layer address here), or some
-intermediate stop on the way to that destination (if the
+.Xr nhop 9
+of the route, which can either a single nexthop or a nexthop group.
+A nexthop can be a directly connected destination (some protocols will
+put a link-layer address here), or some intermediate stop on the way to that
+destination (if the
 .Dv RTF_GATEWAY
 flag is set).
 .It Vt "int rt_flags" ;
@@ -82,33 +83,8 @@ flag is not present, the
 .Fn rtfree
 function will delete the route from the radix tree when the last
 reference drops.
-.It Vt "int rt_refcnt" ;
-Route entries are reference-counted; this field indicates the number
-of external (to the radix tree) references.
-.It Vt "struct ifnet *rt_ifp" ;
-.It Vt "struct ifaddr *rt_ifa" ;
-These two fields represent the
-.Dq answer ,
-as it were, to the question posed by a route lookup; that is, they
-name the interface and interface address to be used in sending a
-packet to the destination or set of destinations which this route
-represents.
-.It Vt "u_long rt_mtu";
-See description of rmx_mtu below.
 .It Vt "u_long rt_weight";
 See description of rmx_weight below.
-.It Vt "u_long rt_expire";
-See description of rmx_expire below.
-.It Vt "counter64_t rt_pksent";
-See description of rmx_pksent below.
-.It Vt "struct rtentry *rt_gwroute" ;
-This member is a reference to a route whose destination is
-.Va rt_gateway .
-It is only used for
-.Dv RTF_GATEWAY
-routes.
-.It Vt "struct mtx rt_mtx" ;
-Mutex to lock this routing entry.
 .El
 .Pp
 The following flag bits are defined:
@@ -221,13 +197,20 @@ units of
 per second.
 .It Vt "u_long rmx_pksent" ;
 A count of packets successfully sent via this route.
-.It Vt "u_long rmx_filler[4]" ;
+.It Vt "u_long rmx_weight" ;
+The weight of nexthop in multipath route.
+.It Vt "u_long rmx_nhidx" ;
+The kernel index of route nexthop.
+.It Vt "u_long rmx_metric" ;
+The metric of the route, the lowest value wins.
+.It Vt "u_long rmx_filler[1]" ;
 .\" XXX badly named
 Empty space available for protocol-specific information.
 .El
 .Sh SEE ALSO
 .Xr route 4 ,
-.Xr route 8
+.Xr route 8 ,
+.Xr nhop 9
 .Sh HISTORY
 The
 .Vt rtentry
@@ -240,10 +223,3 @@ structure first appeared in
 .Sh AUTHORS
 This manual page was written by
 .An Garrett Wollman .
-.Sh BUGS
-There are a number of historical relics remaining in this interface.
-The
-.Va rt_gateway
-and
-.Va rmx_filler
-fields could be named better.