Documentation/networking/rxrpc.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 The RxRPC protocol driver provides a reliable two-phase transport on top of UDP
8 that can be used to perform RxRPC remote operations.  This is done over sockets
38 RxRPC is a two-layer protocol.  There is a session layer which provides
44 		+-------------+
46 		+-------------+
48 		+-------------+
50 		+-------------+
52 		+-------------+
60  (2) A two-phase protocol.  The client transmits a blob (the request) and then
82      to use - currently only PF_INET is supported.
106  (#) Client-originating packets are marked, thus a transport endpoint can be
126  (#) Calls are two-phase and asymmetric: the client sends its request data,
137  (#) Security is negotiated on a per-connection basis.  The connection is
149  (#) There are two types of positive acknowledgment: hard-ACKs and soft-ACKs.
150      A hard-ACK indicates to the far side that all the data received to a point
151      has been received and processed; a soft-ACK indicates that the data has
152      been received but may yet be discarded and re-requested.  The sender may
153      not discard any transmittable packets until they've been hard-ACK'd.
155  (#) Reception of a reply data packet implicitly hard-ACK's all the data
159      received and the final hard-ACK on the last packet of the reply has
174      connections are handled transparently.  One client socket may be used to
182      the last call currently using it has completed in case a new call is made
186      time [tunable] after the last connection using it discarded, in case a new
189  (#) A client-side connection is only shared between calls if they have
191      would otherwise share the connection).  Non-secured calls would also be
194  (#) A server-side connection is shared if the client says it is.
209      non-zero service ID.
215      be used in all other sendmsgs or recvmsgs associated with that call.  The
218  (#) connect() is used to supply a default destination address for a client
225  (#) A server socket may also be used to make client calls.  To do this, the
227      transport endpoint is used to send the packets.
229  (#) Once the application has received the last message associated with a call,
230      the tag is guaranteed not to be seen again, and so it can be used to pin
236      is received with a last recvmsg.
255  (#) The control data part of the msghdr struct is used for a number of things:
301      (b) it meets a non-data message,
317  (4) If there is more data to be had on a call (it hasn't copied the last byte
318      of the last data message in that phase yet), then MSG_MORE will be
331 	RXRPC_USER_CALL_ID	sr- User ID	App's call specifier
333 	RXRPC_ACK		-rt n/a		Final ACK received
334 	RXRPC_NET_ERROR		-rt error num	Network error on call
335 	RXRPC_BUSY		-rt n/a		Call rejected (server busy)
336 	RXRPC_LOCAL_ERROR	-rt error num	Local error encountered
337 	RXRPC_NEW_CALL		-r- n/a		New call received
338 	RXRPC_ACCEPT		s-- n/a		Accept new call
339 	RXRPC_EXCLUSIVE_CALL	s-- n/a		Make an exclusive client call
340 	RXRPC_UPGRADE_SERVICE	s-- n/a		Client call can be upgraded
341 	RXRPC_TX_LENGTH		s-- data len	Total length of Tx data
348      This is used to indicate the application's call ID.  It's an unsigned long
356      This is can be used by an application to abort a call by passing it to
372      errno-class integer value will be included in the control message data
386      errno-class integer value will be included in the control message data
398      This is used by a server application to attempt to accept a call and
407      This is used to indicate that a client call should be made on a one-off
412      This is used to make a client call to probe if the specified service ID
417      Once this has been used to establish the upgrade capability (or lack
418      thereof) of the server, the service ID returned should be used for all
424      This is used to inform the kernel of the total amount of data that is
448      This is used to specify the description of the key to be used.  The key is
462      This is used to request that new connections should be used for each call
467      This is used to specify the minimum security level required for calls on
478 	 encrypted - which includes the actual packet length.
487      This is used to indicate that a service socket with two bindings may
494      This is a read-only option that writes an int into the buffer indicating
503 (security index 2 - rxkad).  This requires the rxkad module to be loaded and,
554      socket used - usually IPv4 but it can also be IPv6 [TODO].
568      This specifies the local UDP port to be used.  If not given, a random
569      non-privileged port will be used.  A UDP port may be shared between
571      per-RxRPC virtual connection.
605      MSG_MORE should be set in msghdr::msg_flags on all but the last part of
622 	RXRPC_USER_CALL_ID	- specifies the user ID for this call
633 the service - otherwise it will be altered to indicate the service ID the
650      socket used - usually IPv4.
707      the time it is accepted - in which case the first call still on the queue
723      to collect as it arrives.  All but the last piece of the request data will
740      MSG_MORE should be set in msghdr::msg_flags on all but the last message
775 The AF_RXRPC module also provides an interface for use by in-kernel utilities
818      non-NULL).
820      If a key is supplied then this will be used to secure the call instead of
829      with this call (or -1 if unknown at this point).  Setting the data size
831      saving a copy.  The value may not be less than -1.
842      allocated; if it is set, the function may return -ERESTARTSYS.
844      debug_id is the call debugging ID to be used for tracing.  This can be
856      This is used to shut down a previously begun call.  The user_call_ID is
865      This is used to release the caller's ref on an rxrpc call.
879      This is used to supply either the request part of a client call or the
881      data buffers to be used.  msg_iov may not be NULL and must point
882      exclusively to in-kernel virtual addresses.  msg.msg_flags may be given
888      notify_end_rx can be NULL or it can be used to specify a function to be
890      called with a spinlock held to prevent the last DATA packet from being
904       This is used to receive data from either the reply part of a client call
911       satisfied and false if this is the last item of the receive phase.
914       was true; 1 if the buffer was filled, the last DATA packet has been
915       emptied and want_more was false; and -EAGAIN if the function needs to be
918       If the last DATA packet is processed but the buffer contains less than
926       This can be used to see if a call got a service upgrade.
936      This is used to abort a call if it's still in an abortable state.  The
958      The skb->mark field indicates the type of message:
978      be the last one in a sequence with rxrpc_kernel_is_data_last().  When a
979      data message has been used up, rxrpc_kernel_data_consumed() should be
992      This is used to accept an incoming call and to assign it a call ID.  This
1004      This is used to reject the first incoming call on the socket's queue with
1005      a BUSY message.  -ENODATA is returned if there were no incoming calls.
1006      Other errors may be returned if the call had been aborted (-ECONNABORTED)
1007      or had timed out (-ETIME).
1013      This is used to allocate a null RxRPC key that can be used to indicate
1021      This is used to find the remote peer address of a call.
1030      call.  It's intended to be used for setting the reply size as the request
1076      This value can be used to determine if the remote client has been
1087      aborted and -ETIME or -ETIMEDOUT will be returned.
1108      request-ack flag set before we honour the flag and actually send the
1118      generate a soft-ACK to tell the sender that it doesn't need to resend.
1123      received queue have been consumed before we generate a hard-ACK to tell
1146      The amount of time in seconds after a connection was last used before we
1153      The amount of time in seconds after a transport was last used before we
1171      packet.  Non-terminal packets in a jumbo packet must contain a four byte