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

+11

Documentation/networking/rxrpc.rst

··· 1172 1172 header plus exactly 1412 bytes of data. The terminal packet must contain 1173 1173 a four byte header plus any amount of data. In any event, a jumbo packet 1174 1174 may not exceed rxrpc_rx_mtu in size. 1175 + 1176 + 1177 + API Function Reference 1178 + ====================== 1179 + 1180 + .. kernel-doc:: net/rxrpc/af_rxrpc.c 1181 + .. kernel-doc:: net/rxrpc/key.c 1182 + .. kernel-doc:: net/rxrpc/peer_object.c 1183 + .. kernel-doc:: net/rxrpc/recvmsg.c 1184 + .. kernel-doc:: net/rxrpc/sendmsg.c 1185 + .. kernel-doc:: net/rxrpc/server_key.c

+17 -4

net/rxrpc/af_rxrpc.c

··· 265 265 * @gfp: Allocation flags 266 266 * 267 267 * Lookup or create a remote transport endpoint record for the specified 268 - * address and return it with a ref held. 268 + * address. 269 + * 270 + * Return: The peer record found with a reference, %NULL if no record is found 271 + * or a negative error code if the address is invalid or unsupported. 269 272 */ 270 273 struct rxrpc_peer *rxrpc_kernel_lookup_peer(struct socket *sock, 271 274 struct sockaddr_rxrpc *srx, gfp_t gfp) ··· 286 283 287 284 /** 288 285 * rxrpc_kernel_get_peer - Get a reference on a peer 289 - * @peer: The peer to get a reference on. 286 + * @peer: The peer to get a reference on (may be NULL). 290 287 * 291 - * Get a record for the remote peer in a call. 288 + * Get a reference for a remote peer record (if not NULL). 289 + * 290 + * Return: The @peer argument. 292 291 */ 293 292 struct rxrpc_peer *rxrpc_kernel_get_peer(struct rxrpc_peer *peer) 294 293 { ··· 301 296 /** 302 297 * rxrpc_kernel_put_peer - Allow a kernel app to drop a peer reference 303 298 * @peer: The peer to drop a ref on 299 + * 300 + * Drop a reference on a peer record. 304 301 */ 305 302 void rxrpc_kernel_put_peer(struct rxrpc_peer *peer) 306 303 { ··· 327 320 * 328 321 * Allow a kernel service to begin a call on the nominated socket. This just 329 322 * sets up all the internal tracking structures and allocates connection and 330 - * call IDs as appropriate. The call to be used is returned. 323 + * call IDs as appropriate. 331 324 * 332 325 * The default socket destination address and security may be overridden by 333 326 * supplying @srx and @key. 327 + * 328 + * Return: The new call or an error code. 334 329 */ 335 330 struct rxrpc_call *rxrpc_kernel_begin_call(struct socket *sock, 336 331 struct rxrpc_peer *peer, ··· 446 437 * 447 438 * Allow a kernel service to find out whether a call is still alive - whether 448 439 * it has completed successfully and all received data has been consumed. 440 + * 441 + * Return: %true if the call is still ongoing and %false if it has completed. 449 442 */ 450 443 bool rxrpc_kernel_check_life(const struct socket *sock, 451 444 const struct rxrpc_call *call) ··· 467 456 * 468 457 * Allow a kernel service to retrieve the epoch value from a service call to 469 458 * see if the client at the other end rebooted. 459 + * 460 + * Return: The epoch of the call's connection. 470 461 */ 471 462 u32 rxrpc_kernel_get_epoch(struct socket *sock, struct rxrpc_call *call) 472 463 {

+2

net/rxrpc/key.c

··· 531 531 * 532 532 * Generate a null RxRPC key that can be used to indicate anonymous security is 533 533 * required for a particular domain. 534 + * 535 + * Return: The new key or a negative error code. 534 536 */ 535 537 struct key *rxrpc_get_null_key(const char *keyname) 536 538 {

+18 -4

net/rxrpc/peer_object.c

··· 475 475 * @call: The call to query 476 476 * 477 477 * Get a record for the remote peer in a call. 478 + * 479 + * Return: The call's peer record. 478 480 */ 479 481 struct rxrpc_peer *rxrpc_kernel_get_call_peer(struct socket *sock, struct rxrpc_call *call) 480 482 { ··· 488 486 * rxrpc_kernel_get_srtt - Get a call's peer smoothed RTT 489 487 * @peer: The peer to query 490 488 * 491 - * Get the call's peer smoothed RTT in uS or UINT_MAX if we have no samples. 489 + * Get the call's peer smoothed RTT. 490 + * 491 + * Return: The RTT in uS or %UINT_MAX if we have no samples. 492 492 */ 493 493 unsigned int rxrpc_kernel_get_srtt(const struct rxrpc_peer *peer) 494 494 { ··· 503 499 * @peer: The peer to query 504 500 * 505 501 * Get a pointer to the address from a peer record. The caller is responsible 506 - * for making sure that the address is not deallocated. 502 + * for making sure that the address is not deallocated. A fake address will be 503 + * substituted if %peer in NULL. 504 + * 505 + * Return: The rxrpc address record or a fake record. 507 506 */ 508 507 const struct sockaddr_rxrpc *rxrpc_kernel_remote_srx(const struct rxrpc_peer *peer) 509 508 { ··· 519 512 * @peer: The peer to query 520 513 * 521 514 * Get a pointer to the transport address from a peer record. The caller is 522 - * responsible for making sure that the address is not deallocated. 515 + * responsible for making sure that the address is not deallocated. A fake 516 + * address will be substituted if %peer in NULL. 517 + * 518 + * Return: The transport address record or a fake record. 523 519 */ 524 520 const struct sockaddr *rxrpc_kernel_remote_addr(const struct rxrpc_peer *peer) 525 521 { ··· 537 527 * @app_data: The data to set 538 528 * 539 529 * Set the app-specific data on a peer. AF_RXRPC makes no effort to retain 540 - * anything the data might refer to. The previous app_data is returned. 530 + * anything the data might refer to. 531 + * 532 + * Return: The previous app_data. 541 533 */ 542 534 unsigned long rxrpc_kernel_set_peer_data(struct rxrpc_peer *peer, unsigned long app_data) 543 535 { ··· 552 540 * @peer: The peer to query 553 541 * 554 542 * Retrieve the app-specific data from a peer. 543 + * 544 + * Return: The peer's app data. 555 545 */ 556 546 unsigned long rxrpc_kernel_get_peer_data(const struct rxrpc_peer *peer) 557 547 {

+6 -6

net/rxrpc/recvmsg.c

··· 477 477 * @_service: Where to store the actual service ID (may be upgraded) 478 478 * 479 479 * Allow a kernel service to receive data and pick up information about the 480 - * state of a call. Returns 0 if got what was asked for and there's more 481 - * available, 1 if we got what was asked for and we're at the end of the data 482 - * and -EAGAIN if we need more data. 480 + * state of a call. Note that *@_abort should also be initialised to %0. 483 481 * 484 - * Note that we may return -EAGAIN to drain empty packets at the end of the 485 - * data, even if we've already copied over the requested data. 482 + * Note that we may return %-EAGAIN to drain empty packets at the end 483 + * of the data, even if we've already copied over the requested data. 486 484 * 487 - * *_abort should also be initialised to 0. 485 + * Return: %0 if got what was asked for and there's more available, %1 486 + * if we got what was asked for and we're at the end of the data and 487 + * %-EAGAIN if we need more data. 488 488 */ 489 489 int rxrpc_kernel_recv_data(struct socket *sock, struct rxrpc_call *call, 490 490 struct iov_iter *iter, size_t *_len,

+5 -2

net/rxrpc/sendmsg.c

··· 794 794 * appropriate to sending data. No control data should be supplied in @msg, 795 795 * nor should an address be supplied. MSG_MORE should be flagged if there's 796 796 * more data to come, otherwise this data will end the transmission phase. 797 + * 798 + * Return: %0 if successful and a negative error code otherwise. 797 799 */ 798 800 int rxrpc_kernel_send_data(struct socket *sock, struct rxrpc_call *call, 799 801 struct msghdr *msg, size_t len, ··· 831 829 * @error: Local error value 832 830 * @why: Indication as to why. 833 831 * 834 - * Allow a kernel service to abort a call, if it's still in an abortable state 835 - * and return true if the call was aborted, false if it was already complete. 832 + * Allow a kernel service to abort a call if it's still in an abortable state. 833 + * 834 + * Return: %true if the call was aborted, %false if it was already complete. 836 835 */ 837 836 bool rxrpc_kernel_abort_call(struct socket *sock, struct rxrpc_call *call, 838 837 u32 abort_code, int error, enum rxrpc_abort_reason why)

+2

net/rxrpc/server_key.c

··· 152 152 * 153 153 * Set the server security keyring on an rxrpc socket. This is used to provide 154 154 * the encryption keys for a kernel service. 155 + * 156 + * Return: %0 if successful and a negative error code otherwise. 155 157 */ 156 158 int rxrpc_sock_set_security_keyring(struct sock *sk, struct key *keyring) 157 159 {

Configure Feed

Configure Feed