Commit f7cf335c authored by Jakub Kicinski's avatar Jakub Kicinski

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.orgSigned-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parents 7fe2af16 2fc30dec
...@@ -101,6 +101,7 @@ Contents: ...@@ -101,6 +101,7 @@ Contents:
tcp-thin tcp-thin
team team
timestamping timestamping
tipc
tproxy tproxy
tuntap tuntap
udplite udplite
......
.. 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:
...@@ -72,6 +72,7 @@ static int tipc_l2_rcv_msg(struct sk_buff *skb, struct net_device *dev, ...@@ -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 * tipc_media_find - locates specified media object by name
* @name: name to locate
*/ */
struct tipc_media *tipc_media_find(const char *name) struct tipc_media *tipc_media_find(const char *name)
{ {
...@@ -86,6 +87,7 @@ 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 * media_find_id - locates specified media object by type identifier
* @type: type identifier to locate
*/ */
static struct tipc_media *media_find_id(u8 type) static struct tipc_media *media_find_id(u8 type)
{ {
...@@ -100,6 +102,9 @@ 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 * 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) 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) ...@@ -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: ptr to bearer name string
* @name_parts: ptr to area for bearer name components (or NULL if not needed) * @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, static int bearer_name_validate(const char *name,
struct tipc_bearer_names *name_parts) struct tipc_bearer_names *name_parts)
...@@ -166,6 +171,8 @@ static int bearer_name_validate(const char *name, ...@@ -166,6 +171,8 @@ static int bearer_name_validate(const char *name,
/** /**
* tipc_bearer_find - locates bearer object with matching bearer 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) 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) ...@@ -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 * 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, static int tipc_enable_bearer(struct net *net, const char *name,
u32 disc_domain, u32 prio, u32 disc_domain, u32 prio,
...@@ -342,6 +354,8 @@ static int tipc_enable_bearer(struct net *net, const char *name, ...@@ -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 * 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) static int tipc_reset_bearer(struct net *net, struct tipc_bearer *b)
{ {
...@@ -363,7 +377,9 @@ void tipc_bearer_put(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. * Note: This routine assumes caller holds RTNL lock.
*/ */
...@@ -434,6 +450,7 @@ int tipc_enable_l2_media(struct net *net, struct tipc_bearer *b, ...@@ -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 /* 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 * 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) ...@@ -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 * tipc_l2_send_msg - send a TIPC packet out over an L2 interface
* @net: the associated network namespace
* @skb: the packet to be sent * @skb: the packet to be sent
* @b: the bearer through which the packet is to be sent * @b: the bearer through which the packet is to be sent
* @dest: peer destination address * @dest: peer destination address
......
...@@ -93,7 +93,8 @@ struct tipc_bearer; ...@@ -93,7 +93,8 @@ struct tipc_bearer;
* @raw2addr: convert from raw addr format to media addr format * @raw2addr: convert from raw addr format to media addr format
* @priority: default link (and bearer) priority * @priority: default link (and bearer) priority
* @tolerance: default time (in ms) before declaring link failure * @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 * @mtu: max packet size bearer can support for media type not dependent on
* underlying device MTU * underlying device MTU
* @type_id: TIPC media identifier * @type_id: TIPC media identifier
...@@ -138,12 +139,15 @@ struct tipc_media { ...@@ -138,12 +139,15 @@ struct tipc_media {
* @pt: packet type for bearer * @pt: packet type for bearer
* @rcu: rcu struct for tipc_bearer * @rcu: rcu struct for tipc_bearer
* @priority: default link priority for 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 * @tolerance: default link tolerance for bearer
* @domain: network domain to which links can be established * @domain: network domain to which links can be established
* @identity: array index of this bearer within TIPC bearer array * @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 * @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 * Note: media-specific code is responsible for initialization of the fields
* indicated below when a bearer is enabled; TIPC's generic bearer code takes * indicated below when a bearer is enabled; TIPC's generic bearer code takes
......
// SPDX-License-Identifier: GPL-2.0 // SPDX-License-Identifier: GPL-2.0
/** /*
* net/tipc/crypto.c: TIPC crypto for key handling & packet en/decryption * net/tipc/crypto.c: TIPC crypto for key handling & packet en/decryption
* *
* Copyright (c) 2019, Ericsson AB * Copyright (c) 2019, Ericsson AB
...@@ -51,7 +51,7 @@ ...@@ -51,7 +51,7 @@
#define TIPC_REKEYING_INTV_DEF (60 * 24) /* default: 1 day */ #define TIPC_REKEYING_INTV_DEF (60 * 24) /* default: 1 day */
/** /*
* TIPC Key ids * TIPC Key ids
*/ */
enum { enum {
...@@ -63,7 +63,7 @@ enum { ...@@ -63,7 +63,7 @@ enum {
KEY_MAX = KEY_3, KEY_MAX = KEY_3,
}; };
/** /*
* TIPC Crypto statistics * TIPC Crypto statistics
*/ */
enum { enum {
...@@ -90,7 +90,7 @@ int sysctl_tipc_max_tfms __read_mostly = TIPC_MAX_TFMS_DEF; ...@@ -90,7 +90,7 @@ int sysctl_tipc_max_tfms __read_mostly = TIPC_MAX_TFMS_DEF;
/* Key exchange switch, default: on */ /* Key exchange switch, default: on */
int sysctl_tipc_key_exchange_enabled __read_mostly = 1; int sysctl_tipc_key_exchange_enabled __read_mostly = 1;
/** /*
* struct tipc_key - TIPC keys' status indicator * struct tipc_key - TIPC keys' status indicator
* *
* 7 6 5 4 3 2 1 0 * 7 6 5 4 3 2 1 0
...@@ -123,6 +123,8 @@ struct tipc_key { ...@@ -123,6 +123,8 @@ struct tipc_key {
/** /**
* struct tipc_tfm - TIPC TFM structure to form a list of TFMs * 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 tipc_tfm {
struct crypto_aead *tfm; struct crypto_aead *tfm;
...@@ -138,7 +140,7 @@ struct tipc_tfm { ...@@ -138,7 +140,7 @@ struct tipc_tfm {
* @salt: the key's SALT value * @salt: the key's SALT value
* @authsize: authentication tag size (max = 16) * @authsize: authentication tag size (max = 16)
* @mode: crypto mode is applied to the key * @mode: crypto mode is applied to the key
* @hint[]: a hint for user key * @hint: a hint for user key
* @rcu: struct rcu_head * @rcu: struct rcu_head
* @key: the aead key * @key: the aead key
* @gen: the key's generation * @gen: the key's generation
...@@ -166,6 +168,7 @@ struct tipc_aead { ...@@ -166,6 +168,7 @@ struct tipc_aead {
/** /**
* struct tipc_crypto_stats - TIPC Crypto statistics * struct tipc_crypto_stats - TIPC Crypto statistics
* @stat: array of crypto statistics
*/ */
struct tipc_crypto_stats { struct tipc_crypto_stats {
unsigned int stat[MAX_STATS]; unsigned int stat[MAX_STATS];
...@@ -194,6 +197,7 @@ struct tipc_crypto_stats { ...@@ -194,6 +197,7 @@ struct tipc_crypto_stats {
* @key_master: flag indicates if master key exists * @key_master: flag indicates if master key exists
* @legacy_user: flag indicates if a peer joins w/o master key (for bwd comp.) * @legacy_user: flag indicates if a peer joins w/o master key (for bwd comp.)
* @nokey: no key indication * @nokey: no key indication
* @flags: combined flags field
* @lock: tipc_key lock * @lock: tipc_key lock
*/ */
struct tipc_crypto { struct tipc_crypto {
...@@ -324,6 +328,8 @@ do { \ ...@@ -324,6 +328,8 @@ do { \
/** /**
* tipc_aead_key_validate - Validate a AEAD user key * 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) 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) ...@@ -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 * 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) 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, ...@@ -714,9 +721,9 @@ static void *tipc_aead_mem_alloc(struct crypto_aead *tfm,
* @__dnode: TIPC dest node if "known" * @__dnode: TIPC dest node if "known"
* *
* Return: * Return:
* 0 : if the encryption has completed * * 0 : if the encryption has completed
* -EINPROGRESS/-EBUSY : if a callback will be performed * * -EINPROGRESS/-EBUSY : if a callback will be performed
* < 0 : the encryption has failed * * < 0 : the encryption has failed
*/ */
static int tipc_aead_encrypt(struct tipc_aead *aead, struct sk_buff *skb, static int tipc_aead_encrypt(struct tipc_aead *aead, struct sk_buff *skb,
struct tipc_bearer *b, struct tipc_bearer *b,
...@@ -870,9 +877,9 @@ static void tipc_aead_encrypt_done(struct crypto_async_request *base, int err) ...@@ -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 * @b: TIPC bearer where the message has been received
* *
* Return: * Return:
* 0 : if the decryption has completed * * 0 : if the decryption has completed
* -EINPROGRESS/-EBUSY : if a callback will be performed * * -EINPROGRESS/-EBUSY : if a callback will be performed
* < 0 : the decryption has failed * * < 0 : the decryption has failed
*/ */
static int tipc_aead_decrypt(struct net *net, struct tipc_aead *aead, static int tipc_aead_decrypt(struct net *net, struct tipc_aead *aead,
struct sk_buff *skb, struct tipc_bearer *b) struct sk_buff *skb, struct tipc_bearer *b)
...@@ -1001,7 +1008,7 @@ static inline int tipc_ehdr_size(struct tipc_ehdr *ehdr) ...@@ -1001,7 +1008,7 @@ static inline int tipc_ehdr_size(struct tipc_ehdr *ehdr)
* tipc_ehdr_validate - Validate an encryption message * tipc_ehdr_validate - Validate an encryption message
* @skb: the message buffer * @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) 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, ...@@ -1674,12 +1681,12 @@ static inline void tipc_crypto_clone_msg(struct net *net, struct sk_buff *_skb,
* Otherwise, the skb is freed! * Otherwise, the skb is freed!
* *
* Return: * Return:
* 0 : the encryption has succeeded (or no encryption) * * 0 : the encryption has succeeded (or no encryption)
* -EINPROGRESS/-EBUSY : the encryption is ongoing, a callback will be made * * -EINPROGRESS/-EBUSY : the encryption is ongoing, a callback will be made
* -ENOKEK : the encryption has failed due to no key * * -ENOKEK : the encryption has failed due to no key
* -EKEYREVOKED : the encryption has failed due to key revoked * * -EKEYREVOKED : the encryption has failed due to key revoked
* -ENOMEM : the encryption has failed due to no memory * * -ENOMEM : the encryption has failed due to no memory
* < 0 : the encryption has failed due to other reasons * * < 0 : the encryption has failed due to other reasons
*/ */
int tipc_crypto_xmit(struct net *net, struct sk_buff **skb, int tipc_crypto_xmit(struct net *net, struct sk_buff **skb,
struct tipc_bearer *b, struct tipc_media_addr *dst, struct tipc_bearer *b, struct tipc_media_addr *dst,
...@@ -1799,12 +1806,12 @@ int tipc_crypto_xmit(struct net *net, struct sk_buff **skb, ...@@ -1799,12 +1806,12 @@ int tipc_crypto_xmit(struct net *net, struct sk_buff **skb,
* cluster key(s) can be taken for decryption (- recursive). * cluster key(s) can be taken for decryption (- recursive).
* *
* Return: * Return:
* 0 : the decryption has successfully completed * * 0 : the decryption has successfully completed
* -EINPROGRESS/-EBUSY : the decryption is ongoing, a callback will be made * * -EINPROGRESS/-EBUSY : the decryption is ongoing, a callback will be made
* -ENOKEY : the decryption has failed due to no key * * -ENOKEY : the decryption has failed due to no key
* -EBADMSG : the decryption has failed due to bad message * * -EBADMSG : the decryption has failed due to bad message
* -ENOMEM : the decryption has failed due to no memory * * -ENOMEM : the decryption has failed due to no memory
* < 0 : the decryption has failed due to other reasons * * < 0 : the decryption has failed due to other reasons
*/ */
int tipc_crypto_rcv(struct net *net, struct tipc_crypto *rx, int tipc_crypto_rcv(struct net *net, struct tipc_crypto *rx,
struct sk_buff **skb, struct tipc_bearer *b) struct sk_buff **skb, struct tipc_bearer *b)
......
/* SPDX-License-Identifier: GPL-2.0 */ /* SPDX-License-Identifier: GPL-2.0 */
/** /*
* net/tipc/crypto.h: Include file for TIPC crypto * net/tipc/crypto.h: Include file for TIPC crypto
* *
* Copyright (c) 2019, Ericsson AB * Copyright (c) 2019, Ericsson AB
...@@ -53,7 +53,7 @@ ...@@ -53,7 +53,7 @@
#define TIPC_AES_GCM_IV_SIZE 12 #define TIPC_AES_GCM_IV_SIZE 12
#define TIPC_AES_GCM_TAG_SIZE 16 #define TIPC_AES_GCM_TAG_SIZE 16
/** /*
* TIPC crypto modes: * TIPC crypto modes:
* - CLUSTER_KEY: * - CLUSTER_KEY:
* One single key is used for both TX & RX in all nodes in the cluster. * One single key is used for both TX & RX in all nodes in the cluster.
...@@ -69,7 +69,7 @@ enum { ...@@ -69,7 +69,7 @@ enum {
extern int sysctl_tipc_max_tfms __read_mostly; extern int sysctl_tipc_max_tfms __read_mostly;
extern int sysctl_tipc_key_exchange_enabled __read_mostly; extern int sysctl_tipc_key_exchange_enabled __read_mostly;
/** /*
* TIPC encryption message format: * TIPC encryption message format:
* *
* 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 * 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
......
...@@ -74,6 +74,7 @@ struct tipc_discoverer { ...@@ -74,6 +74,7 @@ struct tipc_discoverer {
/** /**
* tipc_disc_init_msg - initialize a link setup message * tipc_disc_init_msg - initialize a link setup message
* @net: the applicable net namespace * @net: the applicable net namespace
* @skb: buffer containing message
* @mtyp: message type (request or response) * @mtyp: message type (request or response)
* @b: ptr to bearer issuing message * @b: ptr to bearer issuing message
*/ */
...@@ -341,7 +342,7 @@ static void tipc_disc_timeout(struct timer_list *t) ...@@ -341,7 +342,7 @@ static void tipc_disc_timeout(struct timer_list *t)
* @dest: destination address for request messages * @dest: destination address for request messages
* @skb: pointer to created frame * @skb: pointer to created frame
* *
* Returns 0 if successful, otherwise -errno. * Return: 0 if successful, otherwise -errno.
*/ */
int tipc_disc_create(struct net *net, struct tipc_bearer *b, int tipc_disc_create(struct net *net, struct tipc_bearer *b,
struct tipc_media_addr *dest, struct sk_buff **skb) struct tipc_media_addr *dest, struct sk_buff **skb)
...@@ -380,7 +381,7 @@ int tipc_disc_create(struct net *net, struct tipc_bearer *b, ...@@ -380,7 +381,7 @@ int tipc_disc_create(struct net *net, struct tipc_bearer *b,
/** /**
* tipc_disc_delete - destroy object sending periodic link setup requests * tipc_disc_delete - destroy object sending periodic link setup requests
* @d: ptr to link duest structure * @d: ptr to link dest structure
*/ */
void tipc_disc_delete(struct tipc_discoverer *d) void tipc_disc_delete(struct tipc_discoverer *d)
{ {
......
...@@ -120,6 +120,34 @@ struct tipc_stats { ...@@ -120,6 +120,34 @@ struct tipc_stats {
* @reasm_buf: head of partially reassembled inbound message fragments * @reasm_buf: head of partially reassembled inbound message fragments
* @bc_rcvr: marks that this is a broadcast receiver link * @bc_rcvr: marks that this is a broadcast receiver link
* @stats: collects statistics regarding link activity * @stats: collects statistics regarding link activity
* @session: session to be used by link
* @snd_nxt_state: next send seq number
* @rcv_nxt_state: next rcv seq number
* @in_session: have received ACTIVATE_MSG from peer
* @active: link is active
* @if_name: associated interface name
* @rst_cnt: link reset counter
* @drop_point: seq number for failover handling (FIXME)
* @failover_reasm_skb: saved failover msg ptr (FIXME)
* @failover_deferdq: deferred message queue for failover processing (FIXME)
* @transmq: the link's transmit queue
* @backlog: link's backlog by priority (importance)
* @snd_nxt: next sequence number to be used
* @rcv_unacked: # messages read by user, but not yet acked back to peer
* @deferdq: deferred receive queue
* @window: sliding window size for congestion handling
* @min_win: minimal send window to be used by link
* @ssthresh: slow start threshold for congestion handling
* @max_win: maximal send window to be used by link
* @cong_acks: congestion acks for congestion avoidance (FIXME)
* @checkpoint: seq number for congestion window size handling
* @reasm_tnlmsg: fragmentation/reassembly area for tunnel protocol message
* @last_gap: last gap ack blocks for bcast (FIXME)
* @last_ga: ptr to gap ack blocks
* @bc_rcvlink: the peer specific link used for broadcast reception
* @bc_sndlink: the namespace global link used for broadcast sending
* @nack_state: bcast nack state
* @bc_peer_is_up: peer has acked the bcast init msg
*/ */
struct tipc_link { struct tipc_link {
u32 addr; u32 addr;
...@@ -450,7 +478,6 @@ u32 tipc_link_state(struct tipc_link *l) ...@@ -450,7 +478,6 @@ u32 tipc_link_state(struct tipc_link *l)
* @min_win: minimal send window to be used by link * @min_win: minimal send window to be used by link
* @max_win: maximal send window to be used by link * @max_win: maximal send window to be used by link
* @session: session to be used by link * @session: session to be used by link
* @ownnode: identity of own node
* @peer: node id of peer node * @peer: node id of peer node
* @peer_caps: bitmap describing peer node capabilities * @peer_caps: bitmap describing peer node capabilities
* @bc_sndlink: the namespace global link used for broadcast sending * @bc_sndlink: the namespace global link used for broadcast sending
...@@ -458,8 +485,10 @@ u32 tipc_link_state(struct tipc_link *l) ...@@ -458,8 +485,10 @@ u32 tipc_link_state(struct tipc_link *l)
* @inputq: queue to put messages ready for delivery * @inputq: queue to put messages ready for delivery
* @namedq: queue to put binding table update messages ready for delivery * @namedq: queue to put binding table update messages ready for delivery
* @link: return value, pointer to put the created link * @link: return value, pointer to put the created link
* @self: local unicast link id
* @peer_id: 128-bit ID of peer
* *
* Returns true if link was created, otherwise false * Return: true if link was created, otherwise false
*/ */
bool tipc_link_create(struct net *net, char *if_name, int bearer_id, bool tipc_link_create(struct net *net, char *if_name, int bearer_id,
int tolerance, char net_plane, u32 mtu, int priority, int tolerance, char net_plane, u32 mtu, int priority,
...@@ -532,8 +561,13 @@ bool tipc_link_create(struct net *net, char *if_name, int bearer_id, ...@@ -532,8 +561,13 @@ bool tipc_link_create(struct net *net, char *if_name, int bearer_id,
* @inputq: queue to put messages ready for delivery * @inputq: queue to put messages ready for delivery
* @namedq: queue to put binding table update messages ready for delivery * @namedq: queue to put binding table update messages ready for delivery
* @link: return value, pointer to put the created link * @link: return value, pointer to put the created link
* @ownnode: identity of own node
* @peer: node id of peer node
* @peer_id: 128-bit ID of peer
* @peer_caps: bitmap describing peer node capabilities
* @bc_sndlink: the namespace global link used for broadcast sending
* *
* Returns true if link was created, otherwise false * Return: true if link was created, otherwise false
*/ */
bool tipc_link_bc_create(struct net *net, u32 ownnode, u32 peer, u8 *peer_id, bool tipc_link_bc_create(struct net *net, u32 ownnode, u32 peer, u8 *peer_id,
int mtu, u32 min_win, u32 max_win, u16 peer_caps, int mtu, u32 min_win, u32 max_win, u16 peer_caps,
...@@ -788,7 +822,7 @@ static void link_profile_stats(struct tipc_link *l) ...@@ -788,7 +822,7 @@ static void link_profile_stats(struct tipc_link *l)
* tipc_link_too_silent - check if link is "too silent" * tipc_link_too_silent - check if link is "too silent"
* @l: tipc link to be checked * @l: tipc link to be checked
* *
* Returns true if the link 'silent_intv_cnt' is about to reach the * Return: true if the link 'silent_intv_cnt' is about to reach the
* 'abort_limit' value, otherwise false * 'abort_limit' value, otherwise false
*/ */
bool tipc_link_too_silent(struct tipc_link *l) bool tipc_link_too_silent(struct tipc_link *l)
...@@ -990,8 +1024,8 @@ void tipc_link_reset(struct tipc_link *l) ...@@ -990,8 +1024,8 @@ void tipc_link_reset(struct tipc_link *l)
* @xmitq: returned list of packets to be sent by caller * @xmitq: returned list of packets to be sent by caller
* *
* Consumes the buffer chain. * Consumes the buffer chain.
* Returns 0 if success, or errno: -ELINKCONG, -EMSGSIZE or -ENOBUFS
* Messages at TIPC_SYSTEM_IMPORTANCE are always accepted * Messages at TIPC_SYSTEM_IMPORTANCE are always accepted
* Return: 0 if success, or errno: -ELINKCONG, -EMSGSIZE or -ENOBUFS
*/ */
int tipc_link_xmit(struct tipc_link *l, struct sk_buff_head *list, int tipc_link_xmit(struct tipc_link *l, struct sk_buff_head *list,
struct sk_buff_head *xmitq) struct sk_buff_head *xmitq)
...@@ -2376,7 +2410,7 @@ int tipc_link_bc_sync_rcv(struct tipc_link *l, struct tipc_msg *hdr, ...@@ -2376,7 +2410,7 @@ int tipc_link_bc_sync_rcv(struct tipc_link *l, struct tipc_msg *hdr,
if (!msg_peer_node_is_up(hdr)) if (!msg_peer_node_is_up(hdr))
return rc; return rc;
/* Open when peer ackowledges our bcast init msg (pkt #1) */ /* Open when peer acknowledges our bcast init msg (pkt #1) */
if (msg_ack(hdr)) if (msg_ack(hdr))
l->bc_peer_is_up = true; l->bc_peer_is_up = true;
......
...@@ -58,10 +58,12 @@ static unsigned int align(unsigned int i) ...@@ -58,10 +58,12 @@ static unsigned int align(unsigned int i)
/** /**
* tipc_buf_acquire - creates a TIPC message buffer * tipc_buf_acquire - creates a TIPC message buffer
* @size: message size (including TIPC header) * @size: message size (including TIPC header)
* @gfp: memory allocation flags
* *
* Returns a new buffer with data pointers set to the specified size. * Return: a new buffer with data pointers set to the specified size.
* *
* NOTE: Headroom is reserved to allow prepending of a data link header. * NOTE:
* Headroom is reserved to allow prepending of a data link header.
* There may also be unrequested tailroom present at the buffer's end. * There may also be unrequested tailroom present at the buffer's end.
*/ */
struct sk_buff *tipc_buf_acquire(u32 size, gfp_t gfp) struct sk_buff *tipc_buf_acquire(u32 size, gfp_t gfp)
...@@ -207,8 +209,9 @@ int tipc_buf_append(struct sk_buff **headbuf, struct sk_buff **buf) ...@@ -207,8 +209,9 @@ int tipc_buf_append(struct sk_buff **headbuf, struct sk_buff **buf)
* @m: the data to be appended * @m: the data to be appended
* @mss: max allowable size of buffer * @mss: max allowable size of buffer
* @dlen: size of data to be appended * @dlen: size of data to be appended
* @txq: queue to appand to * @txq: queue to append to
* Returns the number og 1k blocks appended or errno value *
* Return: the number of 1k blocks appended or errno value
*/ */
int tipc_msg_append(struct tipc_msg *_hdr, struct msghdr *m, int dlen, int tipc_msg_append(struct tipc_msg *_hdr, struct msghdr *m, int dlen,
int mss, struct sk_buff_head *txq) int mss, struct sk_buff_head *txq)
...@@ -312,7 +315,7 @@ bool tipc_msg_validate(struct sk_buff **_skb) ...@@ -312,7 +315,7 @@ bool tipc_msg_validate(struct sk_buff **_skb)
* @pktmax: max size of a fragment incl. the header * @pktmax: max size of a fragment incl. the header
* @frags: returned fragment skb list * @frags: returned fragment skb list
* *
* Returns 0 if the fragmentation is successful, otherwise: -EINVAL * Return: 0 if the fragmentation is successful, otherwise: -EINVAL
* or -ENOMEM * or -ENOMEM
*/ */
int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr, int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr,
...@@ -367,6 +370,7 @@ int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr, ...@@ -367,6 +370,7 @@ int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr,
* tipc_msg_build - create buffer chain containing specified header and data * tipc_msg_build - create buffer chain containing specified header and data
* @mhdr: Message header, to be prepended to data * @mhdr: Message header, to be prepended to data
* @m: User message * @m: User message
* @offset: buffer offset for fragmented messages (FIXME)
* @dsz: Total length of user data * @dsz: Total length of user data
* @pktmax: Max packet size that can be used * @pktmax: Max packet size that can be used
* @list: Buffer or chain of buffers to be returned to caller * @list: Buffer or chain of buffers to be returned to caller
...@@ -374,7 +378,7 @@ int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr, ...@@ -374,7 +378,7 @@ int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr,
* Note that the recursive call we are making here is safe, since it can * Note that the recursive call we are making here is safe, since it can
* logically go only one further level down. * logically go only one further level down.
* *
* Returns message data size or errno: -ENOMEM, -EFAULT * Return: message data size or errno: -ENOMEM, -EFAULT
*/ */
int tipc_msg_build(struct tipc_msg *mhdr, struct msghdr *m, int offset, int tipc_msg_build(struct tipc_msg *mhdr, struct msghdr *m, int offset,
int dsz, int pktmax, struct sk_buff_head *list) int dsz, int pktmax, struct sk_buff_head *list)
...@@ -485,7 +489,7 @@ int tipc_msg_build(struct tipc_msg *mhdr, struct msghdr *m, int offset, ...@@ -485,7 +489,7 @@ int tipc_msg_build(struct tipc_msg *mhdr, struct msghdr *m, int offset,
* @msg: message to be appended * @msg: message to be appended
* @max: max allowable size for the bundle buffer * @max: max allowable size for the bundle buffer
* *
* Returns "true" if bundling has been performed, otherwise "false" * Return: "true" if bundling has been performed, otherwise "false"
*/ */
static bool tipc_msg_bundle(struct sk_buff *bskb, struct tipc_msg *msg, static bool tipc_msg_bundle(struct sk_buff *bskb, struct tipc_msg *msg,
u32 max) u32 max)
...@@ -580,9 +584,9 @@ bool tipc_msg_try_bundle(struct sk_buff *tskb, struct sk_buff **skb, u32 mss, ...@@ -580,9 +584,9 @@ bool tipc_msg_try_bundle(struct sk_buff *tskb, struct sk_buff **skb, u32 mss,
* @skb: buffer to be extracted from. * @skb: buffer to be extracted from.
* @iskb: extracted inner buffer, to be returned * @iskb: extracted inner buffer, to be returned
* @pos: position in outer message of msg to be extracted. * @pos: position in outer message of msg to be extracted.
* Returns position of next msg * Returns position of next msg.
* Consumes outer buffer when last packet extracted * Consumes outer buffer when last packet extracted
* Returns true when there is an extracted buffer, otherwise false * Return: true when there is an extracted buffer, otherwise false
*/ */
bool tipc_msg_extract(struct sk_buff *skb, struct sk_buff **iskb, int *pos) bool tipc_msg_extract(struct sk_buff *skb, struct sk_buff **iskb, int *pos)
{ {
...@@ -626,7 +630,7 @@ bool tipc_msg_extract(struct sk_buff *skb, struct sk_buff **iskb, int *pos) ...@@ -626,7 +630,7 @@ bool tipc_msg_extract(struct sk_buff *skb, struct sk_buff **iskb, int *pos)
* @skb: buffer containing message to be reversed; will be consumed * @skb: buffer containing message to be reversed; will be consumed
* @err: error code to be set in message, if any * @err: error code to be set in message, if any
* Replaces consumed buffer with new one when successful * Replaces consumed buffer with new one when successful
* Returns true if success, otherwise false * Return: true if success, otherwise false
*/ */
bool tipc_msg_reverse(u32 own_node, struct sk_buff **skb, int err) bool tipc_msg_reverse(u32 own_node, struct sk_buff **skb, int err)
{ {
...@@ -698,10 +702,11 @@ bool tipc_msg_skb_clone(struct sk_buff_head *msg, struct sk_buff_head *cpy) ...@@ -698,10 +702,11 @@ bool tipc_msg_skb_clone(struct sk_buff_head *msg, struct sk_buff_head *cpy)
/** /**
* tipc_msg_lookup_dest(): try to find new destination for named message * tipc_msg_lookup_dest(): try to find new destination for named message
* @net: pointer to associated network namespace
* @skb: the buffer containing the message. * @skb: the buffer containing the message.
* @err: error code to be used by caller if lookup fails * @err: error code to be used by caller if lookup fails
* Does not consume buffer * Does not consume buffer
* Returns true if a destination is found, false otherwise * Return: true if a destination is found, false otherwise
*/ */
bool tipc_msg_lookup_dest(struct net *net, struct sk_buff *skb, int *err) bool tipc_msg_lookup_dest(struct net *net, struct sk_buff *skb, int *err)
{ {
......
...@@ -50,6 +50,8 @@ struct distr_queue_item { ...@@ -50,6 +50,8 @@ struct distr_queue_item {
/** /**
* publ_to_item - add publication info to a publication message * publ_to_item - add publication info to a publication message
* @p: publication info
* @i: location of item in the message
*/ */
static void publ_to_item(struct distr_item *i, struct publication *p) static void publ_to_item(struct distr_item *i, struct publication *p)
{ {
...@@ -62,6 +64,10 @@ static void publ_to_item(struct distr_item *i, struct publication *p) ...@@ -62,6 +64,10 @@ static void publ_to_item(struct distr_item *i, struct publication *p)
/** /**
* named_prepare_buf - allocate & initialize a publication message * named_prepare_buf - allocate & initialize a publication message
* @net: the associated network namespace
* @type: message type
* @size: payload size
* @dest: destination node
* *
* The buffer returned is of size INT_H_SIZE + payload size * The buffer returned is of size INT_H_SIZE + payload size
*/ */
...@@ -83,6 +89,8 @@ static struct sk_buff *named_prepare_buf(struct net *net, u32 type, u32 size, ...@@ -83,6 +89,8 @@ static struct sk_buff *named_prepare_buf(struct net *net, u32 type, u32 size,
/** /**
* tipc_named_publish - tell other nodes about a new publication by this node * tipc_named_publish - tell other nodes about a new publication by this node
* @net: the associated network namespace
* @publ: the new publication
*/ */
struct sk_buff *tipc_named_publish(struct net *net, struct publication *publ) struct sk_buff *tipc_named_publish(struct net *net, struct publication *publ)
{ {
...@@ -111,6 +119,8 @@ struct sk_buff *tipc_named_publish(struct net *net, struct publication *publ) ...@@ -111,6 +119,8 @@ struct sk_buff *tipc_named_publish(struct net *net, struct publication *publ)
/** /**
* tipc_named_withdraw - tell other nodes about a withdrawn publication by this node * tipc_named_withdraw - tell other nodes about a withdrawn publication by this node
* @net: the associated network namespace
* @publ: the withdrawn publication
*/ */
struct sk_buff *tipc_named_withdraw(struct net *net, struct publication *publ) struct sk_buff *tipc_named_withdraw(struct net *net, struct publication *publ)
{ {
...@@ -138,9 +148,11 @@ struct sk_buff *tipc_named_withdraw(struct net *net, struct publication *publ) ...@@ -138,9 +148,11 @@ struct sk_buff *tipc_named_withdraw(struct net *net, struct publication *publ)
/** /**
* named_distribute - prepare name info for bulk distribution to another node * named_distribute - prepare name info for bulk distribution to another node
* @net: the associated network namespace
* @list: list of messages (buffers) to be returned from this function * @list: list of messages (buffers) to be returned from this function
* @dnode: node to be updated * @dnode: node to be updated
* @pls: linked list of publication items to be packed into buffer chain * @pls: linked list of publication items to be packed into buffer chain
* @seqno: sequence number for this message
*/ */
static void named_distribute(struct net *net, struct sk_buff_head *list, static void named_distribute(struct net *net, struct sk_buff_head *list,
u32 dnode, struct list_head *pls, u16 seqno) u32 dnode, struct list_head *pls, u16 seqno)
...@@ -194,6 +206,9 @@ static void named_distribute(struct net *net, struct sk_buff_head *list, ...@@ -194,6 +206,9 @@ static void named_distribute(struct net *net, struct sk_buff_head *list,
/** /**
* tipc_named_node_up - tell specified node about all publications by this node * tipc_named_node_up - tell specified node about all publications by this node
* @net: the associated network namespace
* @dnode: destination node
* @capabilities: peer node's capabilities
*/ */
void tipc_named_node_up(struct net *net, u32 dnode, u16 capabilities) void tipc_named_node_up(struct net *net, u32 dnode, u16 capabilities)
{ {
...@@ -217,6 +232,9 @@ void tipc_named_node_up(struct net *net, u32 dnode, u16 capabilities) ...@@ -217,6 +232,9 @@ void tipc_named_node_up(struct net *net, u32 dnode, u16 capabilities)
/** /**
* tipc_publ_purge - remove publication associated with a failed node * tipc_publ_purge - remove publication associated with a failed node
* @net: the associated network namespace
* @publ: the publication to remove
* @addr: failed node's address
* *
* Invoked for each publication issued by a newly failed node. * Invoked for each publication issued by a newly failed node.
* Removes publication structure from name table & deletes it. * Removes publication structure from name table & deletes it.
...@@ -263,9 +281,13 @@ void tipc_publ_notify(struct net *net, struct list_head *nsub_list, ...@@ -263,9 +281,13 @@ void tipc_publ_notify(struct net *net, struct list_head *nsub_list,
/** /**
* tipc_update_nametbl - try to process a nametable update and notify * tipc_update_nametbl - try to process a nametable update and notify
* subscribers * subscribers
* @net: the associated network namespace
* @i: location of item in the message
* @node: node address
* @dtype: name distributor message type
* *
* tipc_nametbl_lock must be held. * tipc_nametbl_lock must be held.
* Returns the publication item if successful, otherwise NULL. * Return: the publication item if successful, otherwise NULL.
*/ */
static bool tipc_update_nametbl(struct net *net, struct distr_item *i, static bool tipc_update_nametbl(struct net *net, struct distr_item *i,
u32 node, u32 dtype) u32 node, u32 dtype)
...@@ -347,6 +369,10 @@ static struct sk_buff *tipc_named_dequeue(struct sk_buff_head *namedq, ...@@ -347,6 +369,10 @@ static struct sk_buff *tipc_named_dequeue(struct sk_buff_head *namedq,
/** /**
* tipc_named_rcv - process name table update messages sent by another node * tipc_named_rcv - process name table update messages sent by another node
* @net: the associated network namespace
* @namedq: queue to receive from
* @rcv_nxt: store last received seqno here
* @open: last bulk msg was received (FIXME)
*/ */
void tipc_named_rcv(struct net *net, struct sk_buff_head *namedq, void tipc_named_rcv(struct net *net, struct sk_buff_head *namedq,
u16 *rcv_nxt, bool *open) u16 *rcv_nxt, bool *open)
...@@ -374,6 +400,7 @@ void tipc_named_rcv(struct net *net, struct sk_buff_head *namedq, ...@@ -374,6 +400,7 @@ void tipc_named_rcv(struct net *net, struct sk_buff_head *namedq,
/** /**
* tipc_named_reinit - re-initialize local publications * tipc_named_reinit - re-initialize local publications
* @net: the associated network namespace
* *
* This routine is called whenever TIPC networking is enabled. * This routine is called whenever TIPC networking is enabled.
* All name table entries published by this node are updated to reflect * All name table entries published by this node are updated to reflect
......
...@@ -46,7 +46,7 @@ ...@@ -46,7 +46,7 @@
* @type: name sequence type * @type: name sequence type
* @lower: name sequence lower bound * @lower: name sequence lower bound
* @upper: name sequence upper bound * @upper: name sequence upper bound
* @ref: publishing port reference * @port: publishing port reference
* @key: publication key * @key: publication key
* *
* ===> All fields are stored in network byte order. <=== * ===> All fields are stored in network byte order. <===
......
...@@ -104,7 +104,8 @@ RB_DECLARE_CALLBACKS_MAX(static, sr_callbacks, ...@@ -104,7 +104,8 @@ RB_DECLARE_CALLBACKS_MAX(static, sr_callbacks,
* range match * range match
* @sr: the service range pointer as a loop cursor * @sr: the service range pointer as a loop cursor
* @sc: the pointer to tipc service which holds the service range rbtree * @sc: the pointer to tipc service which holds the service range rbtree
* @start, end: the range (end >= start) for matching * @start: beginning of the search range (end >= start) for matching
* @end: end of the search range (end >= start) for matching
*/ */
#define service_range_foreach_match(sr, sc, start, end) \ #define service_range_foreach_match(sr, sc, start, end) \
for (sr = service_range_match_first((sc)->ranges.rb_node, \ for (sr = service_range_match_first((sc)->ranges.rb_node, \
...@@ -118,7 +119,8 @@ RB_DECLARE_CALLBACKS_MAX(static, sr_callbacks, ...@@ -118,7 +119,8 @@ RB_DECLARE_CALLBACKS_MAX(static, sr_callbacks,
/** /**
* service_range_match_first - find first service range matching a range * service_range_match_first - find first service range matching a range
* @n: the root node of service range rbtree for searching * @n: the root node of service range rbtree for searching
* @start, end: the range (end >= start) for matching * @start: beginning of the search range (end >= start) for matching
* @end: end of the search range (end >= start) for matching
* *
* Return: the leftmost service range node in the rbtree that overlaps the * Return: the leftmost service range node in the rbtree that overlaps the
* specific range if any. Otherwise, returns NULL. * specific range if any. Otherwise, returns NULL.
...@@ -167,7 +169,8 @@ static struct service_range *service_range_match_first(struct rb_node *n, ...@@ -167,7 +169,8 @@ static struct service_range *service_range_match_first(struct rb_node *n,
/** /**
* service_range_match_next - find next service range matching a range * service_range_match_next - find next service range matching a range
* @n: a node in service range rbtree from which the searching starts * @n: a node in service range rbtree from which the searching starts
* @start, end: the range (end >= start) for matching * @start: beginning of the search range (end >= start) for matching
* @end: end of the search range (end >= start) for matching
* *
* Return: the next service range node to the given node in the rbtree that * Return: the next service range node to the given node in the rbtree that
* overlaps the specific range if any. Otherwise, returns NULL. * overlaps the specific range if any. Otherwise, returns NULL.
...@@ -219,6 +222,13 @@ static int hash(int x) ...@@ -219,6 +222,13 @@ static int hash(int x)
/** /**
* tipc_publ_create - create a publication structure * tipc_publ_create - create a publication structure
* @type: name sequence type
* @lower: name sequence lower bound
* @upper: name sequence upper bound
* @scope: publication scope
* @node: network address of publishing socket
* @port: publishing port
* @key: publication key
*/ */
static struct publication *tipc_publ_create(u32 type, u32 lower, u32 upper, static struct publication *tipc_publ_create(u32 type, u32 lower, u32 upper,
u32 scope, u32 node, u32 port, u32 scope, u32 node, u32 port,
...@@ -246,6 +256,8 @@ static struct publication *tipc_publ_create(u32 type, u32 lower, u32 upper, ...@@ -246,6 +256,8 @@ static struct publication *tipc_publ_create(u32 type, u32 lower, u32 upper,
/** /**
* tipc_service_create - create a service structure for the specified 'type' * tipc_service_create - create a service structure for the specified 'type'
* @type: service type
* @hd: name_table services list
* *
* Allocates a single range structure and sets it to all 0's. * Allocates a single range structure and sets it to all 0's.
*/ */
...@@ -362,6 +374,9 @@ static struct publication *tipc_service_insert_publ(struct net *net, ...@@ -362,6 +374,9 @@ static struct publication *tipc_service_insert_publ(struct net *net,
/** /**
* tipc_service_remove_publ - remove a publication from a service * tipc_service_remove_publ - remove a publication from a service
* @sr: service_range to remove publication from
* @node: target node
* @key: target publication key
*/ */
static struct publication *tipc_service_remove_publ(struct service_range *sr, static struct publication *tipc_service_remove_publ(struct service_range *sr,
u32 node, u32 key) u32 node, u32 key)
...@@ -378,7 +393,7 @@ static struct publication *tipc_service_remove_publ(struct service_range *sr, ...@@ -378,7 +393,7 @@ static struct publication *tipc_service_remove_publ(struct service_range *sr,
return NULL; return NULL;
} }
/** /*
* Code reused: time_after32() for the same purpose * Code reused: time_after32() for the same purpose
*/ */
#define publication_after(pa, pb) time_after32((pa)->id, (pb)->id) #define publication_after(pa, pb) time_after32((pa)->id, (pb)->id)
...@@ -396,6 +411,8 @@ static int tipc_publ_sort(void *priv, struct list_head *a, ...@@ -396,6 +411,8 @@ static int tipc_publ_sort(void *priv, struct list_head *a,
* tipc_service_subscribe - attach a subscription, and optionally * tipc_service_subscribe - attach a subscription, and optionally
* issue the prescribed number of events if there is any service * issue the prescribed number of events if there is any service
* range overlapping with the requested range * range overlapping with the requested range
* @service: the tipc_service to attach the @sub to
* @sub: the subscription to attach
*/ */
static void tipc_service_subscribe(struct tipc_service *service, static void tipc_service_subscribe(struct tipc_service *service,
struct tipc_subscription *sub) struct tipc_subscription *sub)
...@@ -529,8 +546,10 @@ struct publication *tipc_nametbl_remove_publ(struct net *net, u32 type, ...@@ -529,8 +546,10 @@ struct publication *tipc_nametbl_remove_publ(struct net *net, u32 type,
/** /**
* tipc_nametbl_translate - perform service instance to socket translation * tipc_nametbl_translate - perform service instance to socket translation
* * @net: network namespace
* On entry, 'dnode' is the search domain used during translation. * @type: message type
* @instance: message instance
* @dnode: the search domain used during translation
* *
* On exit: * On exit:
* - if translation is deferred to another node, leave 'dnode' unchanged and * - if translation is deferred to another node, leave 'dnode' unchanged and
...@@ -757,6 +776,11 @@ struct publication *tipc_nametbl_publish(struct net *net, u32 type, u32 lower, ...@@ -757,6 +776,11 @@ struct publication *tipc_nametbl_publish(struct net *net, u32 type, u32 lower,
/** /**
* tipc_nametbl_withdraw - withdraw a service binding * tipc_nametbl_withdraw - withdraw a service binding
* @net: network namespace
* @type: service type
* @lower: service range lower bound
* @upper: service range upper bound
* @key: target publication key
*/ */
int tipc_nametbl_withdraw(struct net *net, u32 type, u32 lower, int tipc_nametbl_withdraw(struct net *net, u32 type, u32 lower,
u32 upper, u32 key) u32 upper, u32 key)
...@@ -792,6 +816,7 @@ int tipc_nametbl_withdraw(struct net *net, u32 type, u32 lower, ...@@ -792,6 +816,7 @@ int tipc_nametbl_withdraw(struct net *net, u32 type, u32 lower,
/** /**
* tipc_nametbl_subscribe - add a subscription object to the name table * tipc_nametbl_subscribe - add a subscription object to the name table
* @sub: subscription to add
*/ */
bool tipc_nametbl_subscribe(struct tipc_subscription *sub) bool tipc_nametbl_subscribe(struct tipc_subscription *sub)
{ {
...@@ -822,6 +847,7 @@ bool tipc_nametbl_subscribe(struct tipc_subscription *sub) ...@@ -822,6 +847,7 @@ bool tipc_nametbl_subscribe(struct tipc_subscription *sub)
/** /**
* tipc_nametbl_unsubscribe - remove a subscription object from name table * tipc_nametbl_unsubscribe - remove a subscription object from name table
* @sub: subscription to remove
*/ */
void tipc_nametbl_unsubscribe(struct tipc_subscription *sub) void tipc_nametbl_unsubscribe(struct tipc_subscription *sub)
{ {
...@@ -872,6 +898,8 @@ int tipc_nametbl_init(struct net *net) ...@@ -872,6 +898,8 @@ int tipc_nametbl_init(struct net *net)
/** /**
* tipc_service_delete - purge all publications for a service and delete it * tipc_service_delete - purge all publications for a service and delete it
* @net: the associated network namespace
* @sc: tipc_service to delete
*/ */
static void tipc_service_delete(struct net *net, struct tipc_service *sc) static void tipc_service_delete(struct net *net, struct tipc_service *sc)
{ {
......
...@@ -60,7 +60,7 @@ struct tipc_group; ...@@ -60,7 +60,7 @@ struct tipc_group;
* @key: publication key, unique across the cluster * @key: publication key, unique across the cluster
* @id: publication id * @id: publication id
* @binding_node: all publications from the same node which bound this one * @binding_node: all publications from the same node which bound this one
* - Remote publications: in node->publ_list * - Remote publications: in node->publ_list;
* Used by node/name distr to withdraw publications when node is lost * Used by node/name distr to withdraw publications when node is lost
* - Local/node scope publications: in name_table->node_scope list * - Local/node scope publications: in name_table->node_scope list
* - Local/cluster scope publications: in name_table->cluster_scope list * - Local/cluster scope publications: in name_table->cluster_scope list
...@@ -92,13 +92,16 @@ struct publication { ...@@ -92,13 +92,16 @@ struct publication {
/** /**
* struct name_table - table containing all existing port name publications * struct name_table - table containing all existing port name publications
* @seq_hlist: name sequence hash lists * @services: name sequence hash lists
* @node_scope: all local publications with node scope * @node_scope: all local publications with node scope
* - used by name_distr during re-init of name table * - used by name_distr during re-init of name table
* @cluster_scope: all local publications with cluster scope * @cluster_scope: all local publications with cluster scope
* - used by name_distr to send bulk updates to new nodes * - used by name_distr to send bulk updates to new nodes
* - used by name_distr during re-init of name table * - used by name_distr during re-init of name table
* @cluster_scope_lock: lock for accessing @cluster_scope
* @local_publ_count: number of publications issued by this node * @local_publ_count: number of publications issued by this node
* @rc_dests: destination node counter
* @snd_nxt: next sequence number to be used
*/ */
struct name_table { struct name_table {
struct hlist_head services[TIPC_NAMETBL_SIZE]; struct hlist_head services[TIPC_NAMETBL_SIZE];
......
...@@ -82,7 +82,7 @@ struct tipc_bclink_entry { ...@@ -82,7 +82,7 @@ struct tipc_bclink_entry {
/** /**
* struct tipc_node - TIPC node structure * struct tipc_node - TIPC node structure
* @addr: network address of node * @addr: network address of node
* @ref: reference counter to node object * @kref: reference counter to node object
* @lock: rwlock governing access to structure * @lock: rwlock governing access to structure
* @net: the applicable net namespace * @net: the applicable net namespace
* @hash: links to adjacent nodes in unsorted hash chain * @hash: links to adjacent nodes in unsorted hash chain
...@@ -90,9 +90,11 @@ struct tipc_bclink_entry { ...@@ -90,9 +90,11 @@ struct tipc_bclink_entry {
* @namedq: pointer to name table input queue with name table messages * @namedq: pointer to name table input queue with name table messages
* @active_links: bearer ids of active links, used as index into links[] array * @active_links: bearer ids of active links, used as index into links[] array
* @links: array containing references to all links to node * @links: array containing references to all links to node
* @bc_entry: broadcast link entry
* @action_flags: bit mask of different types of node actions * @action_flags: bit mask of different types of node actions
* @state: connectivity state vs peer node * @state: connectivity state vs peer node
* @preliminary: a preliminary node or not * @preliminary: a preliminary node or not
* @failover_sent: failover sent or not
* @sync_point: sequence number where synch/failover is finished * @sync_point: sequence number where synch/failover is finished
* @list: links to adjacent nodes in sorted list of cluster's nodes * @list: links to adjacent nodes in sorted list of cluster's nodes
* @working_links: number of working links to node (both active and standby) * @working_links: number of working links to node (both active and standby)
...@@ -100,9 +102,16 @@ struct tipc_bclink_entry { ...@@ -100,9 +102,16 @@ struct tipc_bclink_entry {
* @capabilities: bitmap, indicating peer node's functional capabilities * @capabilities: bitmap, indicating peer node's functional capabilities
* @signature: node instance identifier * @signature: node instance identifier
* @link_id: local and remote bearer ids of changing link, if any * @link_id: local and remote bearer ids of changing link, if any
* @peer_id: 128-bit ID of peer
* @peer_id_string: ID string of peer
* @publ_list: list of publications * @publ_list: list of publications
* @conn_sks: list of connections (FIXME)
* @timer: node's keepalive timer
* @keepalive_intv: keepalive interval in milliseconds
* @rcu: rcu struct for tipc_node * @rcu: rcu struct for tipc_node
* @delete_at: indicates the time for deleting a down node * @delete_at: indicates the time for deleting a down node
* @peer_net: peer's net namespace
* @peer_hash_mix: hash for this peer (FIXME)
* @crypto_rx: RX crypto handler * @crypto_rx: RX crypto handler
*/ */
struct tipc_node { struct tipc_node {
...@@ -267,6 +276,7 @@ char *tipc_node_get_id_str(struct tipc_node *node) ...@@ -267,6 +276,7 @@ char *tipc_node_get_id_str(struct tipc_node *node)
#ifdef CONFIG_TIPC_CRYPTO #ifdef CONFIG_TIPC_CRYPTO
/** /**
* tipc_node_crypto_rx - Retrieve crypto RX handle from node * tipc_node_crypto_rx - Retrieve crypto RX handle from node
* @__n: target tipc_node
* Note: node ref counter must be held first! * Note: node ref counter must be held first!
*/ */
struct tipc_crypto *tipc_node_crypto_rx(struct tipc_node *__n) struct tipc_crypto *tipc_node_crypto_rx(struct tipc_node *__n)
...@@ -814,6 +824,9 @@ static void tipc_node_timeout(struct timer_list *t) ...@@ -814,6 +824,9 @@ static void tipc_node_timeout(struct timer_list *t)
/** /**
* __tipc_node_link_up - handle addition of link * __tipc_node_link_up - handle addition of link
* @n: target tipc_node
* @bearer_id: id of the bearer
* @xmitq: queue for messages to be xmited on
* Node lock must be held by caller * Node lock must be held by caller
* Link becomes active (alone or shared) or standby, depending on its priority. * Link becomes active (alone or shared) or standby, depending on its priority.
*/ */
...@@ -880,6 +893,9 @@ static void __tipc_node_link_up(struct tipc_node *n, int bearer_id, ...@@ -880,6 +893,9 @@ static void __tipc_node_link_up(struct tipc_node *n, int bearer_id,
/** /**
* tipc_node_link_up - handle addition of link * tipc_node_link_up - handle addition of link
* @n: target tipc_node
* @bearer_id: id of the bearer
* @xmitq: queue for messages to be xmited on
* *
* Link becomes active (alone or shared) or standby, depending on its priority. * Link becomes active (alone or shared) or standby, depending on its priority.
*/ */
...@@ -900,7 +916,8 @@ static void tipc_node_link_up(struct tipc_node *n, int bearer_id, ...@@ -900,7 +916,8 @@ static void tipc_node_link_up(struct tipc_node *n, int bearer_id,
* *
* This function is only called in a very special situation where link * This function is only called in a very special situation where link
* failover can be already started on peer node but not on this node. * failover can be already started on peer node but not on this node.
* This can happen when e.g. * This can happen when e.g.::
*
* 1. Both links <1A-2A>, <1B-2B> down * 1. Both links <1A-2A>, <1B-2B> down
* 2. Link endpoint 2A up, but 1A still down (e.g. due to network * 2. Link endpoint 2A up, but 1A still down (e.g. due to network
* disturbance, wrong session, etc.) * disturbance, wrong session, etc.)
...@@ -940,6 +957,10 @@ static void tipc_node_link_failover(struct tipc_node *n, struct tipc_link *l, ...@@ -940,6 +957,10 @@ static void tipc_node_link_failover(struct tipc_node *n, struct tipc_link *l,
/** /**
* __tipc_node_link_down - handle loss of link * __tipc_node_link_down - handle loss of link
* @n: target tipc_node
* @bearer_id: id of the bearer
* @xmitq: queue for messages to be xmited on
* @maddr: output media address of the bearer
*/ */
static void __tipc_node_link_down(struct tipc_node *n, int *bearer_id, static void __tipc_node_link_down(struct tipc_node *n, int *bearer_id,
struct sk_buff_head *xmitq, struct sk_buff_head *xmitq,
...@@ -1525,11 +1546,13 @@ static void node_lost_contact(struct tipc_node *n, ...@@ -1525,11 +1546,13 @@ static void node_lost_contact(struct tipc_node *n,
/** /**
* tipc_node_get_linkname - get the name of a link * tipc_node_get_linkname - get the name of a link
* *
* @net: the applicable net namespace
* @bearer_id: id of the bearer * @bearer_id: id of the bearer
* @addr: peer node address * @addr: peer node address
* @linkname: link name output buffer * @linkname: link name output buffer
* @len: size of @linkname output buffer
* *
* Returns 0 on success * Return: 0 on success
*/ */
int tipc_node_get_linkname(struct net *net, u32 bearer_id, u32 addr, int tipc_node_get_linkname(struct net *net, u32 bearer_id, u32 addr,
char *linkname, size_t len) char *linkname, size_t len)
...@@ -1648,7 +1671,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list) ...@@ -1648,7 +1671,7 @@ static void tipc_lxc_xmit(struct net *peer_net, struct sk_buff_head *list)
* @dnode: address of destination node * @dnode: address of destination node
* @selector: a number used for deterministic link selection * @selector: a number used for deterministic link selection
* Consumes the buffer chain. * Consumes the buffer chain.
* Returns 0 if success, otherwise: -ELINKCONG,-EHOSTUNREACH,-EMSGSIZE,-ENOBUF * Return: 0 if success, otherwise: -ELINKCONG,-EHOSTUNREACH,-EMSGSIZE,-ENOBUF
*/ */
int tipc_node_xmit(struct net *net, struct sk_buff_head *list, int tipc_node_xmit(struct net *net, struct sk_buff_head *list,
u32 dnode, int selector) u32 dnode, int selector)
...@@ -1881,9 +1904,11 @@ static void tipc_node_bc_rcv(struct net *net, struct sk_buff *skb, int bearer_id ...@@ -1881,9 +1904,11 @@ static void tipc_node_bc_rcv(struct net *net, struct sk_buff *skb, int bearer_id
/** /**
* tipc_node_check_state - check and if necessary update node state * tipc_node_check_state - check and if necessary update node state
* @n: target tipc_node
* @skb: TIPC packet * @skb: TIPC packet
* @bearer_id: identity of bearer delivering the packet * @bearer_id: identity of bearer delivering the packet
* Returns true if state and msg are ok, otherwise false * @xmitq: queue for messages to be xmited on
* Return: true if state and msg are ok, otherwise false
*/ */
static bool tipc_node_check_state(struct tipc_node *n, struct sk_buff *skb, static bool tipc_node_check_state(struct tipc_node *n, struct sk_buff *skb,
int bearer_id, struct sk_buff_head *xmitq) int bearer_id, struct sk_buff_head *xmitq)
......
This diff is collapsed.
...@@ -56,10 +56,12 @@ static void tipc_sub_send_event(struct tipc_subscription *sub, ...@@ -56,10 +56,12 @@ static void tipc_sub_send_event(struct tipc_subscription *sub,
} }
/** /**
* tipc_sub_check_overlap - test for subscription overlap with the * tipc_sub_check_overlap - test for subscription overlap with the given values
* given values * @seq: tipc_name_seq to check
* @found_lower: lower value to test
* @found_upper: upper value to test
* *
* Returns 1 if there is overlap, otherwise 0. * Return: 1 if there is overlap, otherwise 0.
*/ */
int tipc_sub_check_overlap(struct tipc_service_range *seq, u32 found_lower, int tipc_sub_check_overlap(struct tipc_service_range *seq, u32 found_lower,
u32 found_upper) u32 found_upper)
......
...@@ -48,12 +48,15 @@ struct tipc_conn; ...@@ -48,12 +48,15 @@ struct tipc_conn;
/** /**
* struct tipc_subscription - TIPC network topology subscription object * struct tipc_subscription - TIPC network topology subscription object
* @subscriber: pointer to its subscriber * @kref: reference count for this subscription
* @seq: name sequence associated with subscription * @net: network namespace associated with subscription
* @timer: timer governing subscription duration (optional) * @timer: timer governing subscription duration (optional)
* @nameseq_list: adjacent subscriptions in name sequence's subscription list * @service_list: adjacent subscriptions in name sequence's subscription list
* @sub_list: adjacent subscriptions in subscriber's subscription list * @sub_list: adjacent subscriptions in subscriber's subscription list
* @evt: template for events generated by subscription * @evt: template for events generated by subscription
* @conid: connection identifier of topology server
* @inactive: true if this subscription is inactive
* @lock: serialize up/down and timer events
*/ */
struct tipc_subscription { struct tipc_subscription {
struct kref kref; struct kref kref;
...@@ -64,7 +67,7 @@ struct tipc_subscription { ...@@ -64,7 +67,7 @@ struct tipc_subscription {
struct tipc_event evt; struct tipc_event evt;
int conid; int conid;
bool inactive; bool inactive;
spinlock_t lock; /* serialize up/down and timer events */ spinlock_t lock;
}; };
struct tipc_subscription *tipc_sub_subscribe(struct net *net, struct tipc_subscription *tipc_sub_subscribe(struct net *net,
......
...@@ -36,7 +36,7 @@ ...@@ -36,7 +36,7 @@
#define CREATE_TRACE_POINTS #define CREATE_TRACE_POINTS
#include "trace.h" #include "trace.h"
/** /*
* socket tuples for filtering in socket traces: * socket tuples for filtering in socket traces:
* (portid, sock type, name type, name lower, name upper) * (portid, sock type, name type, name lower, name upper)
*/ */
......
...@@ -64,6 +64,11 @@ ...@@ -64,6 +64,11 @@
* *
* This is the bearer level originating address used in neighbor discovery * This is the bearer level originating address used in neighbor discovery
* messages, and all fields should be in network byte order * messages, and all fields should be in network byte order
*
* @proto: Ethernet protocol in use
* @port: port being used
* @ipv4: IPv4 address of neighbor
* @ipv6: IPv6 address of neighbor
*/ */
struct udp_media_addr { struct udp_media_addr {
__be16 proto; __be16 proto;
...@@ -88,6 +93,7 @@ struct udp_replicast { ...@@ -88,6 +93,7 @@ struct udp_replicast {
* @ubsock: bearer associated socket * @ubsock: bearer associated socket
* @ifindex: local address scope * @ifindex: local address scope
* @work: used to schedule deferred work on a bearer * @work: used to schedule deferred work on a bearer
* @rcast: associated udp_replicast container
*/ */
struct udp_bearer { struct udp_bearer {
struct tipc_bearer __rcu *bearer; struct tipc_bearer __rcu *bearer;
...@@ -772,7 +778,7 @@ static int tipc_udp_enable(struct net *net, struct tipc_bearer *b, ...@@ -772,7 +778,7 @@ static int tipc_udp_enable(struct net *net, struct tipc_bearer *b,
if (err) if (err)
goto free; goto free;
/** /*
* The bcast media address port is used for all peers and the ip * The bcast media address port is used for all peers and the ip
* is used if it's a multicast address. * is used if it's a multicast address.
*/ */
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment