iproute2 snippets (ip x) are shown in long-running definition lists instead. Format them as literal code blocks that do the semantic job better. Signed-off-by: Bagas Sanjaya --- Documentation/networking/xfrm_device.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 122204da0fff69..7a13075b5bf06a 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -34,7 +34,7 @@ Right now, there are two types of hardware offload that kernel supports. Userland access to the offload is typically through a system such as libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can be handy when experimenting. An example command might look something -like this for crypto offload: +like this for crypto offload:: ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ reqid 0x07 replay-window 32 \ @@ -42,7 +42,7 @@ like this for crypto offload: sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ offload dev eth4 dir in -and for packet offload +and for packet offload:: ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ reqid 0x07 replay-window 32 \ -- An old man doll... just what I always wanted! - Clara Format xfrm offloading steps as numbered list. Signed-off-by: Bagas Sanjaya --- Documentation/networking/xfrm_device.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 7a13075b5bf06a..86db3f42552dd0 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -153,26 +153,26 @@ the packet's skb. At this point the data should be decrypted but the IPsec headers are still in the packet data; they are removed later up the stack in xfrm_input(). - find and hold the SA that was used to the Rx skb:: +1. Find and hold the SA that was used to the Rx skb:: - get spi, protocol, and destination IP from packet headers + /* get spi, protocol, and destination IP from packet headers */ xs = find xs from (spi, protocol, dest_IP) xfrm_state_hold(xs); - store the state information into the skb:: +2. Store the state information into the skb:: sp = secpath_set(skb); if (!sp) return; sp->xvec[sp->len++] = xs; sp->olen++; - indicate the success and/or error status of the offload:: +3. Indicate the success and/or error status of the offload:: xo = xfrm_offload(skb); xo->flags = CRYPTO_DONE; xo->status = crypto_status; - hand the packet to napi_gro_receive() as usual +4. Hand the packet to napi_gro_receive() as usual. In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn() for RX, and xfrm_replay_overflow_offload_esn for TX. -- An old man doll... just what I always wanted! - Clara Sublists of hardware offload type lists are rendered in combined paragraph due to lack of separator from their parent list. Add it. Signed-off-by: Bagas Sanjaya --- Documentation/networking/xfrm_device.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 86db3f42552dd0..b0d85a5f57d1d5 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -20,11 +20,15 @@ can radically increase throughput and decrease CPU utilization. The XFRM Device interface allows NIC drivers to offer to the stack access to the hardware offload. -Right now, there are two types of hardware offload that kernel supports. +Right now, there are two types of hardware offload that kernel supports: + * IPsec crypto offload: + * NIC performs encrypt/decrypt * Kernel does everything else + * IPsec packet offload: + * NIC performs encrypt/decrypt * NIC does encapsulation * Kernel and NIC have SA and policy in-sync -- An old man doll... just what I always wanted! - Clara List texts are currently aligned at the start of column, rather than after the list marker. Reindent them. Signed-off-by: Bagas Sanjaya --- Documentation/networking/xfrm_sync.rst | 77 +++++++++++++------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst index 6246503ceab2d2..c811c3edfa571a 100644 --- a/Documentation/networking/xfrm_sync.rst +++ b/Documentation/networking/xfrm_sync.rst @@ -88,23 +88,23 @@ to get notified of these events. a) byte value (XFRMA_LTIME_VAL) -This TLV carries the running/current counter for byte lifetime since -last event. + This TLV carries the running/current counter for byte lifetime since + last event. -b)replay value (XFRMA_REPLAY_VAL) +b) replay value (XFRMA_REPLAY_VAL) -This TLV carries the running/current counter for replay sequence since -last event. + This TLV carries the running/current counter for replay sequence since + last event. -c)replay threshold (XFRMA_REPLAY_THRESH) +c) replay threshold (XFRMA_REPLAY_THRESH) -This TLV carries the threshold being used by the kernel to trigger events -when the replay sequence is exceeded. + This TLV carries the threshold being used by the kernel to trigger events + when the replay sequence is exceeded. d) expiry timer (XFRMA_ETIMER_THRESH) -This is a timer value in milliseconds which is used as the nagle -value to rate limit the events. + This is a timer value in milliseconds which is used as the nagle + value to rate limit the events. 3) Default configurations for the parameters: --------------------------------------------- @@ -121,12 +121,14 @@ in case they are not specified. the two sysctls/proc entries are: a) /proc/sys/net/core/sysctl_xfrm_aevent_etime -used to provide default values for the XFRMA_ETIMER_THRESH in incremental -units of time of 100ms. The default is 10 (1 second) + + Used to provide default values for the XFRMA_ETIMER_THRESH in incremental + units of time of 100ms. The default is 10 (1 second) b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth -used to provide default values for XFRMA_REPLAY_THRESH parameter -in incremental packet count. The default is two packets. + + Used to provide default values for XFRMA_REPLAY_THRESH parameter + in incremental packet count. The default is two packets. 4) Message types ---------------- @@ -134,42 +136,43 @@ in incremental packet count. The default is two packets. a) XFRM_MSG_GETAE issued by user-->kernel. XFRM_MSG_GETAE does not carry any TLVs. -The response is a XFRM_MSG_NEWAE which is formatted based on what -XFRM_MSG_GETAE queried for. + The response is a XFRM_MSG_NEWAE which is formatted based on what + XFRM_MSG_GETAE queried for. -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -* if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved -* if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + + * if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved + * if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved b) XFRM_MSG_NEWAE is issued by either user space to configure or kernel to announce events or respond to a XFRM_MSG_GETAE. -i) user --> kernel to configure a specific SA. + i) user --> kernel to configure a specific SA. -any of the values or threshold parameters can be updated by passing the -appropriate TLV. + any of the values or threshold parameters can be updated by passing the + appropriate TLV. -A response is issued back to the sender in user space to indicate success -or failure. + A response is issued back to the sender in user space to indicate success + or failure. -In the case of success, additionally an event with -XFRM_MSG_NEWAE is also issued to any listeners as described in iii). + In the case of success, additionally an event with + XFRM_MSG_NEWAE is also issued to any listeners as described in iii). -ii) kernel->user direction as a response to XFRM_MSG_GETAE + ii) kernel->user direction as a response to XFRM_MSG_GETAE -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -The threshold TLVs will be included if explicitly requested in -the XFRM_MSG_GETAE message. + The threshold TLVs will be included if explicitly requested in + the XFRM_MSG_GETAE message. -iii) kernel->user to report as event if someone sets any values or - thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). - In such a case XFRM_AE_CU flag is set to inform the user that - the change happened as a result of an update. - The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + iii) kernel->user to report as event if someone sets any values or + thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). + In such a case XFRM_AE_CU flag is set to inform the user that + the change happened as a result of an update. + The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -iv) kernel->user to report event when replay threshold or a timeout - is exceeded. + iv) kernel->user to report event when replay threshold or a timeout + is exceeded. In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout happened) is set to inform the user what happened. -- An old man doll... just what I always wanted! - Clara XFRM docs are currently reside in Documentation/networking directory, yet these are distinctive as a group of their own. Move them into xfrm subdirectory. Signed-off-by: Bagas Sanjaya --- Documentation/networking/index.rst | 5 +---- Documentation/networking/xfrm/index.rst | 13 +++++++++++++ Documentation/networking/{ => xfrm}/xfrm_device.rst | 0 Documentation/networking/{ => xfrm}/xfrm_proc.rst | 0 Documentation/networking/{ => xfrm}/xfrm_sync.rst | 6 +++--- Documentation/networking/{ => xfrm}/xfrm_sysctl.rst | 0 6 files changed, 17 insertions(+), 7 deletions(-) create mode 100644 Documentation/networking/xfrm/index.rst rename Documentation/networking/{ => xfrm}/xfrm_device.rst (100%) rename Documentation/networking/{ => xfrm}/xfrm_proc.rst (100%) rename Documentation/networking/{ => xfrm}/xfrm_sync.rst (99%) rename Documentation/networking/{ => xfrm}/xfrm_sysctl.rst (100%) diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index c775cababc8c17..75db2251649b85 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -131,10 +131,7 @@ Contents: vxlan x25 x25-iface - xfrm_device - xfrm_proc - xfrm_sync - xfrm_sysctl + xfrm/index xdp-rx-metadata xsk-tx-metadata diff --git a/Documentation/networking/xfrm/index.rst b/Documentation/networking/xfrm/index.rst new file mode 100644 index 00000000000000..7d866da836fe76 --- /dev/null +++ b/Documentation/networking/xfrm/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +XFRM Framework +============== + +.. toctree:: + :maxdepth: 2 + + xfrm_device + xfrm_proc + xfrm_sync + xfrm_sysctl diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm/xfrm_device.rst similarity index 100% rename from Documentation/networking/xfrm_device.rst rename to Documentation/networking/xfrm/xfrm_device.rst diff --git a/Documentation/networking/xfrm_proc.rst b/Documentation/networking/xfrm/xfrm_proc.rst similarity index 100% rename from Documentation/networking/xfrm_proc.rst rename to Documentation/networking/xfrm/xfrm_proc.rst diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm/xfrm_sync.rst similarity index 99% rename from Documentation/networking/xfrm_sync.rst rename to Documentation/networking/xfrm/xfrm_sync.rst index c811c3edfa571a..41a336e0e7345d 100644 --- a/Documentation/networking/xfrm_sync.rst +++ b/Documentation/networking/xfrm/xfrm_sync.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -==== -XFRM -==== +========= +XFRM sync +========= The sync patches work is based on initial patches from Krisztian and others and additional patches diff --git a/Documentation/networking/xfrm_sysctl.rst b/Documentation/networking/xfrm/xfrm_sysctl.rst similarity index 100% rename from Documentation/networking/xfrm_sysctl.rst rename to Documentation/networking/xfrm/xfrm_sysctl.rst -- An old man doll... just what I always wanted! - Clara XFRM patches are supposed to be sent to maintainers under "NETWORKING [IPSEC]" heading, but it doesn't cover XFRM docs yet. Add the entry. Signed-off-by: Bagas Sanjaya --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index d652f4f27756ef..4f33daad40bed6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -18041,6 +18041,7 @@ L: netdev@vger.kernel.org S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/klassert/ipsec.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/klassert/ipsec-next.git +F: Documentation/networking/xfrm/ F: include/net/xfrm.h F: include/uapi/linux/xfrm.h F: net/ipv4/ah4.c -- An old man doll... just what I always wanted! - Clara