Commit f7cf335c authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

Merge branch 'net-tipc-fix-all-kernel-doc-and-add-tipc-networking-chapter' 

Randy Dunlap says:

====================
net/tipc: fix all kernel-doc and add TIPC networking chapter

Fix lots of net/tipc/ kernel-doc warnings. Add many struct field and
function parameter descriptions.

Then add a TIPC chapter to the networking documentation book.

All patches have been rebased to current net-next.

Note: some of the struct members and function parameters are marked
with "FIXME". They could use some additional descriptions if
someone could help add to them. Thanks.
====================

Link: https://lore.kernel.org/r/20201129183251.7049-1-rdunlap@infradead.org


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parents 7fe2af16 2fc30dec

Documentation/networking/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -101,6 +101,7 @@ Contents: 
   tcp-thin

   team

   timestamping

   tipc

   tproxy

   tuntap

   udplite

Documentation/networking/tipc.rst

0 → 100644
+100 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



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

Linux Kernel TIPC

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



TIPC (Transparent Inter Process Communication) is a protocol that is

specially designed for intra-cluster communication.



For more information about TIPC, see http://tipc.sourceforge.net.



TIPC Base Types

---------------



.. kernel-doc:: net/tipc/subscr.h

   :internal:



.. kernel-doc:: net/tipc/bearer.h

   :internal:



.. kernel-doc:: net/tipc/name_table.h

   :internal:



.. kernel-doc:: net/tipc/name_distr.h

   :internal:



.. kernel-doc:: net/tipc/bcast.c

   :internal:



TIPC Bearer Interfaces

----------------------



.. kernel-doc:: net/tipc/bearer.c

   :internal:



.. kernel-doc:: net/tipc/udp_media.c

   :internal:



TIPC Crypto Interfaces

----------------------



.. kernel-doc:: net/tipc/crypto.c

   :internal:



TIPC Discoverer Interfaces

--------------------------



.. kernel-doc:: net/tipc/discover.c

   :internal:



TIPC Link Interfaces

--------------------



.. kernel-doc:: net/tipc/link.c

   :internal:



TIPC msg Interfaces

-------------------



.. kernel-doc:: net/tipc/msg.c

   :internal:



TIPC Name Interfaces

--------------------



.. kernel-doc:: net/tipc/name_table.c

   :internal:



.. kernel-doc:: net/tipc/name_distr.c

   :internal:



TIPC Node Management Interfaces

-------------------------------



.. kernel-doc:: net/tipc/node.c

   :internal:



TIPC Socket Interfaces

----------------------



.. kernel-doc:: net/tipc/socket.c

   :internal:



TIPC Network Topology Interfaces

--------------------------------



.. kernel-doc:: net/tipc/subscr.c

   :internal:



TIPC Server Interfaces

----------------------



.. kernel-doc:: net/tipc/topsrv.c

   :internal:



TIPC Trace Interfaces

---------------------



.. kernel-doc:: net/tipc/trace.c

   :internal:

net/tipc/bearer.c

+20 −2
Original line number Diff line number Diff line
@@ -72,6 +72,7 @@ static int tipc_l2_rcv_msg(struct sk_buff *skb, struct net_device *dev, 


/**

 * tipc_media_find - locates specified media object by name

 * @name: name to locate

 */

struct tipc_media *tipc_media_find(const char *name)

{
@@ -86,6 +87,7 @@ struct tipc_media *tipc_media_find(const char *name) 


/**

 * media_find_id - locates specified media object by type identifier

 * @type: type identifier to locate

 */

static struct tipc_media *media_find_id(u8 type)

{
@@ -100,6 +102,9 @@ static struct tipc_media *media_find_id(u8 type) 


/**

 * tipc_media_addr_printf - record media address in print buffer

 * @buf: output buffer

 * @len: output buffer size remaining

 * @a: input media address

 */

int tipc_media_addr_printf(char *buf, int len, struct tipc_media_addr *a)

{
@@ -127,7 +132,7 @@ int tipc_media_addr_printf(char *buf, int len, struct tipc_media_addr *a) 
 * @name: ptr to bearer name string

 * @name_parts: ptr to area for bearer name components (or NULL if not needed)

 *

 * Returns 1 if bearer name is valid, otherwise 0.

 * Return: 1 if bearer name is valid, otherwise 0.

 */

static int bearer_name_validate(const char *name,

				struct tipc_bearer_names *name_parts)
@@ -166,6 +171,8 @@ static int bearer_name_validate(const char *name, 


/**

 * tipc_bearer_find - locates bearer object with matching bearer name

 * @net: the applicable net namespace

 * @name: bearer name to locate

 */

struct tipc_bearer *tipc_bearer_find(struct net *net, const char *name)

{
@@ -228,6 +235,11 @@ void tipc_bearer_remove_dest(struct net *net, u32 bearer_id, u32 dest) 


/**

 * tipc_enable_bearer - enable bearer with the given name

 * @net: the applicable net namespace

 * @name: bearer name to enable

 * @disc_domain: bearer domain

 * @prio: bearer priority

 * @attr: nlattr array

 */

static int tipc_enable_bearer(struct net *net, const char *name,

			      u32 disc_domain, u32 prio,
@@ -342,6 +354,8 @@ static int tipc_enable_bearer(struct net *net, const char *name, 


/**

 * tipc_reset_bearer - Reset all links established over this bearer

 * @net: the applicable net namespace

 * @b: the target bearer

 */

static int tipc_reset_bearer(struct net *net, struct tipc_bearer *b)

{
@@ -363,7 +377,9 @@ void tipc_bearer_put(struct tipc_bearer *b) 
}



/**

 * bearer_disable

 * bearer_disable - disable this bearer

 * @net: the applicable net namespace

 * @b: the bearer to disable

 *

 * Note: This routine assumes caller holds RTNL lock.

 */
@@ -434,6 +450,7 @@ int tipc_enable_l2_media(struct net *net, struct tipc_bearer *b, 
}



/* tipc_disable_l2_media - detach TIPC bearer from an L2 interface

 * @b: the target bearer

 *

 * Mark L2 bearer as inactive so that incoming buffers are thrown away

 */
@@ -450,6 +467,7 @@ void tipc_disable_l2_media(struct tipc_bearer *b) 


/**

 * tipc_l2_send_msg - send a TIPC packet out over an L2 interface

 * @net: the associated network namespace

 * @skb: the packet to be sent

 * @b: the bearer through which the packet is to be sent

 * @dest: peer destination address

net/tipc/bearer.h

+7 −3
Original line number Diff line number Diff line
@@ -93,7 +93,8 @@ struct tipc_bearer; 
 * @raw2addr: convert from raw addr format to media addr format

 * @priority: default link (and bearer) priority

 * @tolerance: default time (in ms) before declaring link failure

 * @window: default window (in packets) before declaring link congestion

 * @min_win: minimum window (in packets) before declaring link congestion

 * @max_win: maximum window (in packets) before declaring link congestion

 * @mtu: max packet size bearer can support for media type not dependent on

 * underlying device MTU

 * @type_id: TIPC media identifier
@@ -138,12 +139,15 @@ struct tipc_media { 
 * @pt: packet type for bearer

 * @rcu: rcu struct for tipc_bearer

 * @priority: default link priority for bearer

 * @window: default window size for bearer

 * @min_win: minimum window (in packets) before declaring link congestion

 * @max_win: maximum window (in packets) before declaring link congestion

 * @tolerance: default link tolerance for bearer

 * @domain: network domain to which links can be established

 * @identity: array index of this bearer within TIPC bearer array

 * @link_req: ptr to (optional) structure making periodic link setup requests

 * @disc: ptr to link setup request

 * @net_plane: network plane ('A' through 'H') currently associated with bearer

 * @up: bearer up flag (bit 0)

 * @refcnt: tipc_bearer reference counter

 *

 * Note: media-specific code is responsible for initialization of the fields

 * indicated below when a bearer is enabled; TIPC's generic bearer code takes

net/tipc/crypto.c

+31 −24
Original line number Diff line number Diff line 
// SPDX-License-Identifier: GPL-2.0

/**

/*

 * net/tipc/crypto.c: TIPC crypto for key handling & packet en/decryption

 *

 * Copyright (c) 2019, Ericsson AB
@@ -51,7 +51,7 @@ 


#define TIPC_REKEYING_INTV_DEF	(60 * 24) /* default: 1 day */



/**

/*

 * TIPC Key ids

 */

enum {
@@ -63,7 +63,7 @@ enum { 
	KEY_MAX = KEY_3,

};



/**

/*

 * TIPC Crypto statistics

 */

enum {
@@ -90,7 +90,7 @@ int sysctl_tipc_max_tfms __read_mostly = TIPC_MAX_TFMS_DEF; 
/* Key exchange switch, default: on */

int sysctl_tipc_key_exchange_enabled __read_mostly = 1;



/**

/*

 * struct tipc_key - TIPC keys' status indicator

 *

 *         7     6     5     4     3     2     1     0
@@ -123,6 +123,8 @@ struct tipc_key { 


/**

 * struct tipc_tfm - TIPC TFM structure to form a list of TFMs

 * @tfm: cipher handle/key

 * @list: linked list of TFMs

 */

struct tipc_tfm {

	struct crypto_aead *tfm;
@@ -138,7 +140,7 @@ struct tipc_tfm { 
 * @salt: the key's SALT value

 * @authsize: authentication tag size (max = 16)

 * @mode: crypto mode is applied to the key

 * @hint[]: a hint for user key

 * @hint: a hint for user key

 * @rcu: struct rcu_head

 * @key: the aead key

 * @gen: the key's generation
@@ -166,6 +168,7 @@ struct tipc_aead { 


/**

 * struct tipc_crypto_stats - TIPC Crypto statistics

 * @stat: array of crypto statistics

 */

struct tipc_crypto_stats {

	unsigned int stat[MAX_STATS];
@@ -194,6 +197,7 @@ struct tipc_crypto_stats { 
 * @key_master: flag indicates if master key exists

 * @legacy_user: flag indicates if a peer joins w/o master key (for bwd comp.)

 * @nokey: no key indication

 * @flags: combined flags field

 * @lock: tipc_key lock

 */

struct tipc_crypto {
@@ -324,6 +328,8 @@ do { \ 


/**

 * tipc_aead_key_validate - Validate a AEAD user key

 * @ukey: pointer to user key data

 * @info: netlink info pointer

 */

int tipc_aead_key_validate(struct tipc_aead_key *ukey, struct genl_info *info)

{
@@ -477,6 +483,7 @@ static void tipc_aead_users_set(struct tipc_aead __rcu *aead, int val) 


/**

 * tipc_aead_tfm_next - Move TFM entry to the next one in list and return it

 * @aead: the AEAD key pointer

 */

static struct crypto_aead *tipc_aead_tfm_next(struct tipc_aead *aead)

{
@@ -714,9 +721,9 @@ static void *tipc_aead_mem_alloc(struct crypto_aead *tfm, 
 * @__dnode: TIPC dest node if "known"

 *

 * Return:

 * 0                   : if the encryption has completed

 * -EINPROGRESS/-EBUSY : if a callback will be performed

 * < 0                 : the encryption has failed

 * * 0                   : if the encryption has completed

 * * -EINPROGRESS/-EBUSY : if a callback will be performed

 * * < 0                 : the encryption has failed

 */

static int tipc_aead_encrypt(struct tipc_aead *aead, struct sk_buff *skb,

			     struct tipc_bearer *b,
@@ -870,9 +877,9 @@ static void tipc_aead_encrypt_done(struct crypto_async_request *base, int err) 
 * @b: TIPC bearer where the message has been received

 *

 * Return:

 * 0                   : if the decryption has completed

 * -EINPROGRESS/-EBUSY : if a callback will be performed

 * < 0                 : the decryption has failed

 * * 0                   : if the decryption has completed

 * * -EINPROGRESS/-EBUSY : if a callback will be performed

 * * < 0                 : the decryption has failed

 */

static int tipc_aead_decrypt(struct net *net, struct tipc_aead *aead,

			     struct sk_buff *skb, struct tipc_bearer *b)
@@ -1001,7 +1008,7 @@ static inline int tipc_ehdr_size(struct tipc_ehdr *ehdr) 
 * tipc_ehdr_validate - Validate an encryption message

 * @skb: the message buffer

 *

 * Returns "true" if this is a valid encryption message, otherwise "false"

 * Return: "true" if this is a valid encryption message, otherwise "false"

 */

bool tipc_ehdr_validate(struct sk_buff *skb)

{
@@ -1674,12 +1681,12 @@ static inline void tipc_crypto_clone_msg(struct net *net, struct sk_buff *_skb, 
 * Otherwise, the skb is freed!

 *

 * Return:

 * 0                   : the encryption has succeeded (or no encryption)

 * -EINPROGRESS/-EBUSY : the encryption is ongoing, a callback will be made

 * -ENOKEK             : the encryption has failed due to no key

 * -EKEYREVOKED        : the encryption has failed due to key revoked

 * -ENOMEM             : the encryption has failed due to no memory

 * < 0                 : the encryption has failed due to other reasons

 * * 0                   : the encryption has succeeded (or no encryption)

 * * -EINPROGRESS/-EBUSY : the encryption is ongoing, a callback will be made

 * * -ENOKEK             : the encryption has failed due to no key

 * * -EKEYREVOKED        : the encryption has failed due to key revoked

 * * -ENOMEM             : the encryption has failed due to no memory

 * * < 0                 : the encryption has failed due to other reasons

 */

int tipc_crypto_xmit(struct net *net, struct sk_buff **skb,

		     struct tipc_bearer *b, struct tipc_media_addr *dst,
@@ -1799,12 +1806,12 @@ int tipc_crypto_xmit(struct net *net, struct sk_buff **skb, 
 * cluster key(s) can be taken for decryption (- recursive).

 *

 * Return:

 * 0                   : the decryption has successfully completed

 * -EINPROGRESS/-EBUSY : the decryption is ongoing, a callback will be made

 * -ENOKEY             : the decryption has failed due to no key

 * -EBADMSG            : the decryption has failed due to bad message

 * -ENOMEM             : the decryption has failed due to no memory

 * < 0                 : the decryption has failed due to other reasons

 * * 0                   : the decryption has successfully completed

 * * -EINPROGRESS/-EBUSY : the decryption is ongoing, a callback will be made

 * * -ENOKEY             : the decryption has failed due to no key

 * * -EBADMSG            : the decryption has failed due to bad message

 * * -ENOMEM             : the decryption has failed due to no memory

 * * < 0                 : the decryption has failed due to other reasons

 */

int tipc_crypto_rcv(struct net *net, struct tipc_crypto *rx,

		    struct sk_buff **skb, struct tipc_bearer *b)