openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: networking: convert rds.txt to ReST 

- add SPDX header;
- add a document title;
- mark code blocks and literals as such;
- mark tables as such;
- mark lists as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Santosh Shilimkar <santosh.shilimkar@oracle.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Mauro Carvalho Chehab 2020-04-30 18:04:19 +02:00 committed by David S. Miller
parent 8c6e172002
commit bad5b6e223
3 changed files with 162 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/networking/index.rst
View File

@ -97,6 +97,7 @@ Contents:
proc_net_tcp
radiotap-headers
ray_cs
rds
.. only:: subproject and html

295
Documentation/networking/rds.txt → Documentation/networking/rds.rst
View File

@ -1,3 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
==
RDS
===
Overview
========
@ -24,36 +29,39 @@ as IB.
The high-level semantics of RDS from the application's point of view are
* Addressing
RDS uses IPv4 addresses and 16bit port numbers to identify
the end point of a connection. All socket operations that involve
passing addresses between kernel and user space generally
use a struct sockaddr_in.
The fact that IPv4 addresses are used does not mean the underlying
transport has to be IP-based. In fact, RDS over IB uses a
reliable IB connection; the IP address is used exclusively to
locate the remote node's GID (by ARPing for the given IP).
RDS uses IPv4 addresses and 16bit port numbers to identify
the end point of a connection. All socket operations that involve
passing addresses between kernel and user space generally
use a struct sockaddr_in.
The port space is entirely independent of UDP, TCP or any other
protocol.
The fact that IPv4 addresses are used does not mean the underlying
transport has to be IP-based. In fact, RDS over IB uses a
reliable IB connection; the IP address is used exclusively to
locate the remote node's GID (by ARPing for the given IP).
The port space is entirely independent of UDP, TCP or any other
protocol.
* Socket interface
RDS sockets work *mostly* as you would expect from a BSD
socket. The next section will cover the details. At any rate,
all I/O is performed through the standard BSD socket API.
Some additions like zerocopy support are implemented through
control messages, while other extensions use the getsockopt/
setsockopt calls.
Sockets must be bound before you can send or receive data.
This is needed because binding also selects a transport and
attaches it to the socket. Once bound, the transport assignment
does not change. RDS will tolerate IPs moving around (eg in
a active-active HA scenario), but only as long as the address
doesn't move to a different transport.
RDS sockets work *mostly* as you would expect from a BSD
socket. The next section will cover the details. At any rate,
all I/O is performed through the standard BSD socket API.
Some additions like zerocopy support are implemented through
control messages, while other extensions use the getsockopt/
setsockopt calls.
Sockets must be bound before you can send or receive data.
This is needed because binding also selects a transport and
attaches it to the socket. Once bound, the transport assignment
does not change. RDS will tolerate IPs moving around (eg in
a active-active HA scenario), but only as long as the address
doesn't move to a different transport.
* sysctls
RDS supports a number of sysctls in /proc/sys/net/rds
RDS supports a number of sysctls in /proc/sys/net/rds
Socket Interface
@ -66,89 +74,88 @@ Socket Interface
options.
fd = socket(PF_RDS, SOCK_SEQPACKET, 0);
This creates a new, unbound RDS socket.
This creates a new, unbound RDS socket.
setsockopt(SOL_SOCKET): send and receive buffer size
RDS honors the send and receive buffer size socket options.
You are not allowed to queue more than SO_SNDSIZE bytes to
a socket. A message is queued when sendmsg is called, and
it leaves the queue when the remote system acknowledges
its arrival.
RDS honors the send and receive buffer size socket options.
You are not allowed to queue more than SO_SNDSIZE bytes to
a socket. A message is queued when sendmsg is called, and
it leaves the queue when the remote system acknowledges
its arrival.
The SO_RCVSIZE option controls the maximum receive queue length.
This is a soft limit rather than a hard limit - RDS will
continue to accept and queue incoming messages, even if that
takes the queue length over the limit. However, it will also
mark the port as "congested" and send a congestion update to
the source node. The source node is supposed to throttle any
processes sending to this congested port.
The SO_RCVSIZE option controls the maximum receive queue length.
This is a soft limit rather than a hard limit - RDS will
continue to accept and queue incoming messages, even if that
takes the queue length over the limit. However, it will also
mark the port as "congested" and send a congestion update to
the source node. The source node is supposed to throttle any
processes sending to this congested port.
bind(fd, &sockaddr_in, ...)
This binds the socket to a local IP address and port, and a
transport, if one has not already been selected via the
This binds the socket to a local IP address and port, and a
transport, if one has not already been selected via the
SO_RDS_TRANSPORT socket option
sendmsg(fd, ...)
Sends a message to the indicated recipient. The kernel will
transparently establish the underlying reliable connection
if it isn't up yet.
Sends a message to the indicated recipient. The kernel will
transparently establish the underlying reliable connection
if it isn't up yet.
An attempt to send a message that exceeds SO_SNDSIZE will
return with -EMSGSIZE
An attempt to send a message that exceeds SO_SNDSIZE will
return with -EMSGSIZE
An attempt to send a message that would take the total number
of queued bytes over the SO_SNDSIZE threshold will return
EAGAIN.
An attempt to send a message that would take the total number
of queued bytes over the SO_SNDSIZE threshold will return
EAGAIN.
An attempt to send a message to a destination that is marked
as "congested" will return ENOBUFS.
An attempt to send a message to a destination that is marked
as "congested" will return ENOBUFS.
recvmsg(fd, ...)
Receives a message that was queued to this socket. The sockets
recv queue accounting is adjusted, and if the queue length
drops below SO_SNDSIZE, the port is marked uncongested, and
a congestion update is sent to all peers.
Receives a message that was queued to this socket. The sockets
recv queue accounting is adjusted, and if the queue length
drops below SO_SNDSIZE, the port is marked uncongested, and
a congestion update is sent to all peers.
Applications can ask the RDS kernel module to receive
notifications via control messages (for instance, there is a
notification when a congestion update arrived, or when a RDMA
operation completes). These notifications are received through
the msg.msg_control buffer of struct msghdr. The format of the
messages is described in manpages.
Applications can ask the RDS kernel module to receive
notifications via control messages (for instance, there is a
notification when a congestion update arrived, or when a RDMA
operation completes). These notifications are received through
the msg.msg_control buffer of struct msghdr. The format of the
messages is described in manpages.
poll(fd)
RDS supports the poll interface to allow the application
to implement async I/O.
RDS supports the poll interface to allow the application
to implement async I/O.
POLLIN handling is pretty straightforward. When there's an
incoming message queued to the socket, or a pending notification,
we signal POLLIN.
POLLIN handling is pretty straightforward. When there's an
incoming message queued to the socket, or a pending notification,
we signal POLLIN.
POLLOUT is a little harder. Since you can essentially send
to any destination, RDS will always signal POLLOUT as long as
there's room on the send queue (ie the number of bytes queued
is less than the sendbuf size).
POLLOUT is a little harder. Since you can essentially send
to any destination, RDS will always signal POLLOUT as long as
there's room on the send queue (ie the number of bytes queued
is less than the sendbuf size).
However, the kernel will refuse to accept messages to
a destination marked congested - in this case you will loop
forever if you rely on poll to tell you what to do.
This isn't a trivial problem, but applications can deal with
this - by using congestion notifications, and by checking for
ENOBUFS errors returned by sendmsg.
However, the kernel will refuse to accept messages to
a destination marked congested - in this case you will loop
forever if you rely on poll to tell you what to do.
This isn't a trivial problem, but applications can deal with
this - by using congestion notifications, and by checking for
ENOBUFS errors returned by sendmsg.
setsockopt(SOL_RDS, RDS_CANCEL_SENT_TO, &sockaddr_in)
This allows the application to discard all messages queued to a
specific destination on this particular socket.
This allows the application to discard all messages queued to a
specific destination on this particular socket.
This allows the application to cancel outstanding messages if
it detects a timeout. For instance, if it tried to send a message,
and the remote host is unreachable, RDS will keep trying forever.
The application may decide it's not worth it, and cancel the
operation. In this case, it would use RDS_CANCEL_SENT_TO to
nuke any pending messages.
This allows the application to cancel outstanding messages if
it detects a timeout. For instance, if it tried to send a message,
and the remote host is unreachable, RDS will keep trying forever.
The application may decide it's not worth it, and cancel the
operation. In this case, it would use RDS_CANCEL_SENT_TO to
nuke any pending messages.
setsockopt(fd, SOL_RDS, SO_RDS_TRANSPORT, (int *)&transport ..)
getsockopt(fd, SOL_RDS, SO_RDS_TRANSPORT, (int *)&transport ..)
``setsockopt(fd, SOL_RDS, SO_RDS_TRANSPORT, (int *)&transport ..), getsockopt(fd, SOL_RDS, SO_RDS_TRANSPORT, (int *)&transport ..)``
Set or read an integer defining the underlying
encapsulating transport to be used for RDS packets on the
socket. When setting the option, integer argument may be
@ -180,32 +187,39 @@ RDS Protocol
Message header
The message header is a 'struct rds_header' (see rds.h):
Fields:
h_sequence:
per-packet sequence number
per-packet sequence number
h_ack:
piggybacked acknowledgment of last packet received
piggybacked acknowledgment of last packet received
h_len:
length of data, not including header
length of data, not including header
h_sport:
source port
source port
h_dport:
destination port
destination port
h_flags:
CONG_BITMAP - this is a congestion update bitmap
ACK_REQUIRED - receiver must ack this packet
RETRANSMITTED - packet has previously been sent
Can be:
============= ==================================
CONG_BITMAP this is a congestion update bitmap
ACK_REQUIRED receiver must ack this packet
RETRANSMITTED packet has previously been sent
============= ==================================
h_credit:
indicate to other end of connection that
it has more credits available (i.e. there is
more send room)
indicate to other end of connection that
it has more credits available (i.e. there is
more send room)
h_padding[4]:
unused, for future use
unused, for future use
h_csum:
header checksum
header checksum
h_exthdr:
optional data can be passed here. This is currently used for
passing RDMA-related information.
optional data can be passed here. This is currently used for
passing RDMA-related information.
ACK and retransmit handling
@ -260,7 +274,7 @@ RDS Protocol
RDS Transport Layer
==================
===================
As mentioned above, RDS is not IB-specific. Its code is divided
into a general RDS layer and a transport layer.
@ -281,19 +295,25 @@ RDS Kernel Structures
be sent and sets header fields as needed, based on the socket API.
This is then queued for the individual connection and sent by the
connection's transport.
struct rds_incoming
a generic struct referring to incoming data that can be handed from
the transport to the general code and queued by the general code
while the socket is awoken. It is then passed back to the transport
code to handle the actual copy-to-user.
struct rds_socket
per-socket information
struct rds_connection
per-connection information
struct rds_transport
pointers to transport-specific functions
struct rds_statistics
non-transport-specific statistics
struct rds_cong_map
wraps the raw congestion bitmap, contains rbnode, waitq, etc.
@ -317,53 +337,58 @@ The send path
=============
rds_sendmsg()
struct rds_message built from incoming data
CMSGs parsed (e.g. RDMA ops)
transport connection alloced and connected if not already
rds_message placed on send queue
send worker awoken
- struct rds_message built from incoming data
- CMSGs parsed (e.g. RDMA ops)
- transport connection alloced and connected if not already
- rds_message placed on send queue
- send worker awoken
rds_send_worker()
calls rds_send_xmit() until queue is empty
- calls rds_send_xmit() until queue is empty
rds_send_xmit()
transmits congestion map if one is pending
may set ACK_REQUIRED
calls transport to send either non-RDMA or RDMA message
(RDMA ops never retransmitted)
- transmits congestion map if one is pending
- may set ACK_REQUIRED
- calls transport to send either non-RDMA or RDMA message
(RDMA ops never retransmitted)
rds_ib_xmit()
allocs work requests from send ring
adds any new send credits available to peer (h_credits)
maps the rds_message's sg list
piggybacks ack
populates work requests
post send to connection's queue pair
- allocs work requests from send ring
- adds any new send credits available to peer (h_credits)
- maps the rds_message's sg list
- piggybacks ack
- populates work requests
- post send to connection's queue pair
The recv path
=============
rds_ib_recv_cq_comp_handler()
looks at write completions
unmaps recv buffer from device
no errors, call rds_ib_process_recv()
refill recv ring
- looks at write completions
- unmaps recv buffer from device
- no errors, call rds_ib_process_recv()
- refill recv ring
rds_ib_process_recv()
validate header checksum
copy header to rds_ib_incoming struct if start of a new datagram
add to ibinc's fraglist
if competed datagram:
update cong map if datagram was cong update
call rds_recv_incoming() otherwise
note if ack is required
- validate header checksum
- copy header to rds_ib_incoming struct if start of a new datagram
- add to ibinc's fraglist
- if competed datagram:
- update cong map if datagram was cong update
- call rds_recv_incoming() otherwise
- note if ack is required
rds_recv_incoming()
drop duplicate packets
respond to pings
find the sock associated with this datagram
add to sock queue
wake up sock
do some congestion calculations
- drop duplicate packets
- respond to pings
- find the sock associated with this datagram
- add to sock queue
- wake up sock
- do some congestion calculations
rds_recvmsg
copy data into user iovec
handle CMSGs
return to application
- copy data into user iovec
- handle CMSGs
- return to application
Multipath RDS (mprds)
=====================

2
MAINTAINERS
View File

@ -14219,7 +14219,7 @@ L: linux-rdma@vger.kernel.org
L: rds-devel@oss.oracle.com (moderated for non-subscribers)
S: Supported
W: https://oss.oracle.com/projects/rds/
F: Documentation/networking/rds.txt
F: Documentation/networking/rds.rst
F: net/rds/
RDT - RESOURCE ALLOCATION