Commit 28a79fc9 authored by David Howells's avatar David Howells Committed by Jakub Kicinski
Browse files

rxrpc: kdoc: Update function descriptions and add link from rxrpc.rst 



Update the kerneldoc function descriptions to add "Return:" sections for
AF_RXRPC exported functions that have return values to stop the kdoc
builder from throwing warnings.

Also add links from the rxrpc.rst API doc to add a function API reference
at the end.  (Note that the API doc really needs updating, but that's
beyond this patchset).

Signed-off-by: default avatarDavid Howells <dhowells@redhat.com>
cc: Marc Dionne <marc.dionne@auristor.com>
cc: Simon Horman <horms@kernel.org>
cc: linux-afs@lists.infradead.org
Link: https://patch.msgid.link/20250411095303.2316168-2-dhowells@redhat.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent a4cba7e9

Documentation/networking/rxrpc.rst

+11 −0
Original line number Diff line number Diff line
@@ -1172,3 +1172,14 @@ adjusted through sysctls in /proc/net/rxrpc/: 
     header plus exactly 1412 bytes of data.  The terminal packet must contain

     a four byte header plus any amount of data.  In any event, a jumbo packet

     may not exceed rxrpc_rx_mtu in size.





API Function Reference

======================



.. kernel-doc:: net/rxrpc/af_rxrpc.c

.. kernel-doc:: net/rxrpc/key.c

.. kernel-doc:: net/rxrpc/peer_object.c

.. kernel-doc:: net/rxrpc/recvmsg.c

.. kernel-doc:: net/rxrpc/sendmsg.c

.. kernel-doc:: net/rxrpc/server_key.c

net/rxrpc/af_rxrpc.c

+17 −4
Original line number Diff line number Diff line
@@ -265,7 +265,10 @@ static int rxrpc_listen(struct socket *sock, int backlog) 
 * @gfp: Allocation flags

 *

 * Lookup or create a remote transport endpoint record for the specified

 * address and return it with a ref held.

 * address.

 *

 * Return: The peer record found with a reference, %NULL if no record is found

 * or a negative error code if the address is invalid or unsupported.

 */

struct rxrpc_peer *rxrpc_kernel_lookup_peer(struct socket *sock,

					    struct sockaddr_rxrpc *srx, gfp_t gfp)
@@ -283,9 +286,11 @@ EXPORT_SYMBOL(rxrpc_kernel_lookup_peer); 


/**

 * rxrpc_kernel_get_peer - Get a reference on a peer

 * @peer: The peer to get a reference on.

 * @peer: The peer to get a reference on (may be NULL).

 *

 * Get a reference for a remote peer record (if not NULL).

 *

 * Get a record for the remote peer in a call.

 * Return: The @peer argument.

 */

struct rxrpc_peer *rxrpc_kernel_get_peer(struct rxrpc_peer *peer)

{
@@ -296,6 +301,8 @@ EXPORT_SYMBOL(rxrpc_kernel_get_peer); 
/**

 * rxrpc_kernel_put_peer - Allow a kernel app to drop a peer reference

 * @peer: The peer to drop a ref on

 *

 * Drop a reference on a peer record.

 */

void rxrpc_kernel_put_peer(struct rxrpc_peer *peer)

{
@@ -320,10 +327,12 @@ EXPORT_SYMBOL(rxrpc_kernel_put_peer); 
 *

 * Allow a kernel service to begin a call on the nominated socket.  This just

 * sets up all the internal tracking structures and allocates connection and

 * call IDs as appropriate.  The call to be used is returned.

 * call IDs as appropriate.

 *

 * The default socket destination address and security may be overridden by

 * supplying @srx and @key.

 *

 * Return: The new call or an error code.

 */

struct rxrpc_call *rxrpc_kernel_begin_call(struct socket *sock,

					   struct rxrpc_peer *peer,
@@ -437,6 +446,8 @@ EXPORT_SYMBOL(rxrpc_kernel_put_call); 
 *

 * Allow a kernel service to find out whether a call is still alive - whether

 * it has completed successfully and all received data has been consumed.

 *

 * Return: %true if the call is still ongoing and %false if it has completed.

 */

bool rxrpc_kernel_check_life(const struct socket *sock,

			     const struct rxrpc_call *call)
@@ -456,6 +467,8 @@ EXPORT_SYMBOL(rxrpc_kernel_check_life); 
 *

 * Allow a kernel service to retrieve the epoch value from a service call to

 * see if the client at the other end rebooted.

 *

 * Return: The epoch of the call's connection.

 */

u32 rxrpc_kernel_get_epoch(struct socket *sock, struct rxrpc_call *call)

{

net/rxrpc/key.c

+2 −0
Original line number Diff line number Diff line
@@ -531,6 +531,8 @@ EXPORT_SYMBOL(rxrpc_get_server_data_key); 
 *

 * Generate a null RxRPC key that can be used to indicate anonymous security is

 * required for a particular domain.

 *

 * Return: The new key or a negative error code.

 */

struct key *rxrpc_get_null_key(const char *keyname)

{

net/rxrpc/peer_object.c

+18 −4
Original line number Diff line number Diff line
@@ -475,6 +475,8 @@ void rxrpc_destroy_all_peers(struct rxrpc_net *rxnet) 
 * @call: The call to query

 *

 * Get a record for the remote peer in a call.

 *

 * Return: The call's peer record.

 */

struct rxrpc_peer *rxrpc_kernel_get_call_peer(struct socket *sock, struct rxrpc_call *call)

{
@@ -486,7 +488,9 @@ EXPORT_SYMBOL(rxrpc_kernel_get_call_peer); 
 * rxrpc_kernel_get_srtt - Get a call's peer smoothed RTT

 * @peer: The peer to query

 *

 * Get the call's peer smoothed RTT in uS or UINT_MAX if we have no samples.

 * Get the call's peer smoothed RTT.

 *

 * Return: The RTT in uS or %UINT_MAX if we have no samples.

 */

unsigned int rxrpc_kernel_get_srtt(const struct rxrpc_peer *peer)

{
@@ -499,7 +503,10 @@ EXPORT_SYMBOL(rxrpc_kernel_get_srtt); 
 * @peer: The peer to query

 *

 * Get a pointer to the address from a peer record.  The caller is responsible

 * for making sure that the address is not deallocated.

 * for making sure that the address is not deallocated.  A fake address will be

 * substituted if %peer in NULL.

 *

 * Return: The rxrpc address record or a fake record.

 */

const struct sockaddr_rxrpc *rxrpc_kernel_remote_srx(const struct rxrpc_peer *peer)

{
@@ -512,7 +519,10 @@ EXPORT_SYMBOL(rxrpc_kernel_remote_srx); 
 * @peer: The peer to query

 *

 * Get a pointer to the transport address from a peer record.  The caller is

 * responsible for making sure that the address is not deallocated.

 * responsible for making sure that the address is not deallocated.  A fake

 * address will be substituted if %peer in NULL.

 *

 * Return: The transport address record or a fake record.

 */

const struct sockaddr *rxrpc_kernel_remote_addr(const struct rxrpc_peer *peer)

{
@@ -527,7 +537,9 @@ EXPORT_SYMBOL(rxrpc_kernel_remote_addr); 
 * @app_data: The data to set

 *

 * Set the app-specific data on a peer.  AF_RXRPC makes no effort to retain

 * anything the data might refer to.  The previous app_data is returned.

 * anything the data might refer to.

 *

 * Return: The previous app_data.

 */

unsigned long rxrpc_kernel_set_peer_data(struct rxrpc_peer *peer, unsigned long app_data)

{
@@ -540,6 +552,8 @@ EXPORT_SYMBOL(rxrpc_kernel_set_peer_data); 
 * @peer: The peer to query

 *

 * Retrieve the app-specific data from a peer.

 *

 * Return: The peer's app data.

 */

unsigned long rxrpc_kernel_get_peer_data(const struct rxrpc_peer *peer)

{

net/rxrpc/recvmsg.c

+6 −6
Original line number Diff line number Diff line
@@ -477,14 +477,14 @@ int rxrpc_recvmsg(struct socket *sock, struct msghdr *msg, size_t len, 
 * @_service: Where to store the actual service ID (may be upgraded)

 *

 * Allow a kernel service to receive data and pick up information about the

 * state of a call.  Returns 0 if got what was asked for and there's more

 * available, 1 if we got what was asked for and we're at the end of the data

 * and -EAGAIN if we need more data.

 * state of a call.  Note that *@_abort should also be initialised to %0.

 *

 * Note that we may return -EAGAIN to drain empty packets at the end of the

 * data, even if we've already copied over the requested data.

 * Note that we may return %-EAGAIN to drain empty packets at the end

 * of the data, even if we've already copied over the requested data.

 *

 * *_abort should also be initialised to 0.

 * Return: %0 if got what was asked for and there's more available, %1

 * if we got what was asked for and we're at the end of the data and

 * %-EAGAIN if we need more data.

 */

int rxrpc_kernel_recv_data(struct socket *sock, struct rxrpc_call *call,

			   struct iov_iter *iter, size_t *_len,