Linux Kernel TIPC

Introduction

TIPC (Transparent Inter Process Communication) is a protocol that is specially designed for intra-cluster communication. It can be configured to transmit messages either on UDP or directly across Ethernet. Message delivery is sequence guaranteed, loss free and flow controlled. Latency times are shorter than with any other known protocol, while maximal throughput is comparable to that of TCP.

TIPC Features

  • Cluster wide IPC service

    Have you ever wished you had the convenience of Unix Domain Sockets even when transmitting data between cluster nodes? Where you yourself determine the addresses you want to bind to and use? Where you don't have to perform DNS lookups and worry about IP addresses? Where you don't have to start timers to monitor the continuous existence of peer sockets? And yet without the downsides of that socket type, such as the risk of lingering inodes?

    Welcome to the Transparent Inter Process Communication service, TIPC in short, which gives you all of this, and a lot more.

  • Service Addressing

    A fundamental concept in TIPC is that of Service Addressing which makes it possible for a programmer to chose his own address, bind it to a server socket and let client programs use only that address for sending messages.

  • Service Tracking

    A client wanting to wait for the availability of a server, uses the Service Tracking mechanism to subscribe for binding and unbinding/close events for sockets with the associated service address.

    The service tracking mechanism can also be used for Cluster Topology Tracking, i.e., subscribing for availability/non-availability of cluster nodes.

    Likewise, the service tracking mechanism can be used for Cluster Connectivity Tracking, i.e., subscribing for up/down events for individual links between cluster nodes.

  • Transmission Modes

    Using a service address, a client can send datagram messages to a server socket.

    Using the same address type, it can establish a connection towards an accepting server socket.

    It can also use a service address to create and join a Communication Group, which is the TIPC manifestation of a brokerless message bus.

    Multicast with very good performance and scalability is available both in datagram mode and in communication group mode.

  • Inter Node Links

    Communication between any two nodes in a cluster is maintained by one or two Inter Node Links, which both guarantee data traffic integrity and monitor the peer node's availability.

  • Cluster Scalability

    By applying the Overlapping Ring Monitoring algorithm on the inter node links it is possible to scale TIPC clusters up to 1000 nodes with a maintained neighbor failure discovery time of 1-2 seconds. For smaller clusters this time can be made much shorter.

  • Neighbor Discovery

    Neighbor Node Discovery in the cluster is done by Ethernet broadcast or UDP multicast, when any of those services are available. If not, configured peer IP addresses can be used.

  • Configuration

    When running TIPC in single node mode no configuration whatsoever is needed. When running in cluster mode TIPC must as a minimum be given a node address (before Linux 4.17) and told which interface to attach to. The "tipc" configuration tool makes is possible to add and maintain many more configuration parameters.

  • Performance

    TIPC message transfer latency times are better than in any other known protocol. Maximal byte throughput for inter-node connections is still somewhat lower than for TCP, while they are superior for intra-node and inter-container throughput on the same host.

  • Language Support

    The TIPC user API has support for C, Python, Perl, Ruby, D and Go.

More Information

Implementation

TIPC is implemented as a kernel module in net/tipc/ directory.

TIPC Base Types

struct tipc_subscription

TIPC network topology subscription object

Definition:

struct tipc_subscription {
    struct tipc_subscr s;
    struct tipc_event evt;
    struct kref kref;
    struct net *net;
    struct timer_list timer;
    struct list_head service_list;
    struct list_head sub_list;
    int conid;
    bool inactive;
    spinlock_t lock;
};

Members

s

host-endian copy of the user subscription

evt

template for events generated by subscription

kref

reference count for this subscription

net

network namespace associated with subscription

timer

timer governing subscription duration (optional)

service_list

adjacent subscriptions in name sequence's subscription list

sub_list

adjacent subscriptions in subscriber's subscription list

conid

connection identifier of topology server

inactive

true if this subscription is inactive

lock

serialize up/down and timer events

struct tipc_media_addr

destination address used by TIPC bearers

Definition:

struct tipc_media_addr {
    u8 value[TIPC_MEDIA_INFO_SIZE];
    u8 media_id;
    u8 broadcast;
};

Members

value

address info (format defined by media)

media_id

TIPC media type identifier

broadcast

non-zero if address is a broadcast address

struct tipc_media

Media specific info exposed to generic bearer layer

Definition:

struct tipc_media {
    int (*send_msg)(struct net *net, struct sk_buff *buf,struct tipc_bearer *b, struct tipc_media_addr *dest);
    int (*enable_media)(struct net *net, struct tipc_bearer *b, struct nlattr *attr[]);
    void (*disable_media)(struct tipc_bearer *b);
    int (*addr2str)(struct tipc_media_addr *addr,char *strbuf, int bufsz);
    int (*addr2msg)(char *msg, struct tipc_media_addr *addr);
    int (*msg2addr)(struct tipc_bearer *b,struct tipc_media_addr *addr, char *msg);
    int (*raw2addr)(struct tipc_bearer *b,struct tipc_media_addr *addr, const char *raw);
    u32 priority;
    u32 tolerance;
    u32 min_win;
    u32 max_win;
    u32 mtu;
    u32 type_id;
    u32 hwaddr_len;
    char name[TIPC_MAX_MEDIA_NAME];
};

Members

send_msg

routine which handles buffer transmission

enable_media

routine which enables a media

disable_media

routine which disables a media

addr2str

convert media address format to string

addr2msg

convert from media addr format to discovery msg addr format

msg2addr

convert from discovery msg addr format to media addr format

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

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

hwaddr_len

TIPC media address len

name

media name

struct tipc_bearer

Generic TIPC bearer structure

Definition:

struct tipc_bearer {
    void __rcu *media_ptr;
    u32 mtu;
    struct tipc_media_addr addr;
    char name[TIPC_MAX_BEARER_NAME];
    struct tipc_media *media;
    struct tipc_media_addr bcast_addr;
    struct packet_type pt;
    struct rcu_head rcu;
    u32 priority;
    u32 min_win;
    u32 max_win;
    u32 tolerance;
    u32 domain;
    u32 identity;
    struct tipc_discoverer *disc;
    char net_plane;
    u16 encap_hlen;
    unsigned long up;
    refcount_t refcnt;
};

Members

media_ptr

pointer to additional media-specific information about bearer

mtu

max packet size bearer can support

addr

media-specific address associated with bearer

name

bearer name (format = media:interface)

media

ptr to media structure associated with bearer

bcast_addr

media address used in broadcasting

pt

packet type for bearer

rcu

rcu struct for tipc_bearer

priority

default link priority 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

disc

ptr to link setup request

net_plane

network plane ('A' through 'H') currently associated with bearer

encap_hlen

encap headers length

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 care of initializing all other fields.

struct publication

info about a published service address or range

Definition:

struct publication {
    struct tipc_service_range sr;
    struct tipc_socket_addr sk;
    u16 scope;
    u32 key;
    u32 id;
    struct list_head binding_node;
    struct list_head binding_sock;
    struct list_head local_publ;
    struct list_head all_publ;
    struct list_head list;
    struct rcu_head rcu;
};

Members

sr

service range represented by this publication

sk

address of socket bound to this publication

scope

scope of publication, TIPC_NODE_SCOPE or TIPC_CLUSTER_SCOPE

key

publication key, unique across the cluster

id

publication id

binding_node

all publications from the same node which bound this one - Remote publications: in node->publ_list; Used by node/name distr to withdraw publications when node is lost - Local/node scope publications: in name_table->node_scope list - Local/cluster scope publications: in name_table->cluster_scope list

binding_sock

all publications from the same socket which bound this one Used by socket to withdraw publications when socket is unbound/released

local_publ

list of identical publications made from this node Used by closest_first and multicast receive lookup algorithms

all_publ

all publications identical to this one, whatever node and scope Used by round-robin lookup algorithm

list

to form a list of publications in temporal order

rcu

RCU callback head used for deferred freeing

struct name_table

table containing all existing port name publications

Definition:

struct name_table {
    struct hlist_head services[TIPC_NAMETBL_SIZE];
    struct list_head node_scope;
    struct list_head cluster_scope;
    rwlock_t cluster_scope_lock;
    u32 local_publ_count;
    u32 rc_dests;
    u32 snd_nxt;
};

Members

services

name sequence hash lists

node_scope

all local publications with node scope - used by name_distr during re-init of name table

cluster_scope

all local publications with cluster scope - used by name_distr to send bulk updates to new nodes - 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

rc_dests

destination node counter

snd_nxt

next sequence number to be used

struct distr_item

publication info distributed to other nodes

Definition:

struct distr_item {
    __be32 type;
    __be32 lower;
    __be32 upper;
    __be32 port;
    __be32 key;
};

Members

type

name sequence type

lower

name sequence lower bound

upper

name sequence upper bound

port

publishing port reference

key

publication key

Description

===> All fields are stored in network byte order. <===

First 3 fields identify (name or) name sequence being published. Reference field uniquely identifies port that published name sequence. Key field uniquely identifies publication, in the event a port has multiple publications of the same name sequence.

Note

There is no field that identifies the publishing node because it is the same for all items contained within a publication message.

struct tipc_bc_base

base structure for keeping broadcast send state

Definition:

struct tipc_bc_base {
    struct tipc_link *link;
    struct sk_buff_head inputq;
    int dests[MAX_BEARERS];
    int primary_bearer;
    bool bcast_support;
    bool force_bcast;
    bool rcast_support;
    bool force_rcast;
    int rc_ratio;
    int bc_threshold;
};

Members

link

broadcast send link structure

inputq

data input queue; will only carry SOCK_WAKEUP messages

dests

array keeping number of reachable destinations per bearer

primary_bearer

a bearer having links to all broadcast destinations, if any

bcast_support

indicates if primary bearer, if any, supports broadcast

force_bcast

forces broadcast for multicast traffic

rcast_support

indicates if all peer nodes support replicast

force_rcast

forces replicast for multicast traffic

rc_ratio

dest count as percentage of cluster size where send method changes

bc_threshold

calculated from rc_ratio; if dests > threshold use broadcast

TIPC Bearer Interfaces

struct tipc_media *tipc_media_find(const char *name)

locates specified media object by name

Parameters

const char *name

name to locate

struct tipc_media *media_find_id(u8 type)

locates specified media object by type identifier

Parameters

u8 type

type identifier to locate

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

record media address in print buffer

Parameters

char *buf

output buffer

int len

output buffer size remaining

struct tipc_media_addr *a

input media address

int bearer_name_validate(const char *name, struct tipc_bearer_names *name_parts)

validate & (optionally) deconstruct bearer name

Parameters

const char *name

ptr to bearer name string

struct tipc_bearer_names *name_parts

ptr to area for bearer name components (or NULL if not needed)

Return

1 if bearer name is valid, otherwise 0.

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

locates bearer object with matching bearer name

Parameters

struct net *net

the applicable net namespace

const char *name

bearer name to locate

int tipc_enable_bearer(struct net *net, const char *name, u32 disc_domain, u32 prio, struct nlattr *attr[], struct netlink_ext_ack *extack)

enable bearer with the given name

Parameters

struct net *net

the applicable net namespace

const char *name

bearer name to enable

u32 disc_domain

bearer domain

u32 prio

bearer priority

struct nlattr *attr[]

nlattr array

struct netlink_ext_ack *extack

netlink extended ack

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

Reset all links established over this bearer

Parameters

struct net *net

the applicable net namespace

struct tipc_bearer *b

the target bearer

void bearer_disable(struct net *net, struct tipc_bearer *b)

disable this bearer

Parameters

struct net *net

the applicable net namespace

struct tipc_bearer *b

the bearer to disable

Note

This routine assumes caller holds RTNL lock.

int tipc_l2_send_msg(struct net *net, struct sk_buff *skb, struct tipc_bearer *b, struct tipc_media_addr *dest)

send a TIPC packet out over an L2 interface

Parameters

struct net *net

the associated network namespace

struct sk_buff *skb

the packet to be sent

struct tipc_bearer *b

the bearer through which the packet is to be sent

struct tipc_media_addr *dest

peer destination address

int tipc_l2_rcv_msg(struct sk_buff *skb, struct net_device *dev, struct packet_type *pt, struct net_device *orig_dev)

handle incoming TIPC message from an interface

Parameters

struct sk_buff *skb

the received message

struct net_device *dev

the net device that the packet was received on

struct packet_type *pt

the packet_type structure which was used to register this handler

struct net_device *orig_dev

the original receive net device in case the device is a bond

Description

Accept only packets explicitly sent to this node, or broadcast packets; ignores packets sent using interface multicast, and traffic sent to other nodes (which can happen if interface is running in promiscuous mode).

int tipc_l2_device_event(struct notifier_block *nb, unsigned long evt, void *ptr)

handle device events from network device

Parameters

struct notifier_block *nb

the context of the notification

unsigned long evt

the type of event

void *ptr

the net device that the event was on

Description

This function is called by the Ethernet driver in case of link change event.

struct udp_media_addr

IP/UDP addressing information

Definition:

struct udp_media_addr {
    __be16 proto;
    __be16 port;
    union {
        struct in_addr ipv4;
        struct in6_addr ipv6;
    };
};

Members

proto

Ethernet protocol in use

port

port being used

{unnamed_union}

anonymous

ipv4

IPv4 address of neighbor

ipv6

IPv6 address of neighbor

Description

This is the bearer level originating address used in neighbor discovery messages, and all fields should be in network byte order

struct udp_bearer

ip/udp bearer data structure

Definition:

struct udp_bearer {
    struct tipc_bearer __rcu *bearer;
    struct socket *ubsock;
    u32 ifindex;
    struct work_struct work;
    struct udp_replicast rcast;
};

Members

bearer

associated generic tipc bearer

ubsock

bearer associated socket

ifindex

local address scope

work

used to schedule deferred work on a bearer

rcast

associated udp_replicast container

int tipc_parse_udp_addr(struct nlattr *nla, struct udp_media_addr *addr, u32 *scope_id)

build udp media address from netlink data

Parameters

struct nlattr *nla

netlink attribute containing sockaddr storage aligned address

struct udp_media_addr *addr

tipc media address to fill with address, port and protocol type

u32 *scope_id

IPv6 scope id pointer, not NULL indicates it's required

int tipc_udp_enable(struct net *net, struct tipc_bearer *b, struct nlattr *attrs[])

callback to create a new udp bearer instance

Parameters

struct net *net

network namespace

struct tipc_bearer *b

pointer to generic tipc_bearer

struct nlattr *attrs[]

netlink bearer configuration

Description

validate the bearer parameters and initialize the udp bearer rtnl_lock should be held

TIPC Crypto Interfaces

struct tipc_tfm

TIPC TFM structure to form a list of TFMs

Definition:

struct tipc_tfm {
    struct crypto_aead *tfm;
    struct list_head list;
};

Members

tfm

cipher handle/key

list

linked list of TFMs

struct tipc_aead

TIPC AEAD key structure

Definition:

struct tipc_aead {
#define TIPC_AEAD_HINT_LEN (5);
    struct tipc_tfm * __percpu *tfm_entry;
    struct tipc_crypto *crypto;
    struct tipc_aead *cloned;
    atomic_t users;
    u32 salt;
    u8 authsize;
    u8 mode;
    char hint[2 * TIPC_AEAD_HINT_LEN + 1];
    struct rcu_head rcu;
    struct tipc_aead_key *key;
    u16 gen;
    atomic64_t seqno ;
    refcount_t refcnt ;
};

Members

tfm_entry

per-cpu pointer to one entry in TFM list

crypto

TIPC crypto owns this key

cloned

reference to the source key in case cloning

users

the number of the key users (TX/RX)

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

rcu

struct rcu_head

key

the aead key

gen

the key's generation

seqno

the key seqno (cluster scope)

refcnt

the key reference counter

struct tipc_crypto_stats

TIPC Crypto statistics

Definition:

struct tipc_crypto_stats {
    unsigned int stat[MAX_STATS];
};

Members

stat

array of crypto statistics

struct tipc_crypto

TIPC TX/RX crypto structure

Definition:

struct tipc_crypto {
    struct net *net;
    struct tipc_node *node;
    struct tipc_aead __rcu *aead[KEY_MAX + 1];
    atomic_t peer_rx_active;
    u16 key_gen;
    struct tipc_key key;
    u8 skey_mode;
    struct tipc_aead_key *skey;
    struct workqueue_struct *wq;
    struct delayed_work work;
#define KEY_DISTR_SCHED         1;
#define KEY_DISTR_COMPL         2;
    atomic_t key_distr;
    u32 rekeying_intv;
    struct tipc_crypto_stats __percpu *stats;
    char name[48];
    atomic64_t sndnxt ;
    unsigned long timer1;
    unsigned long timer2;
    union {
        struct {
            u8 working:1;
            u8 key_master:1;
            u8 legacy_user:1;
            u8 nokey: 1;
        };
        u8 flags;
    };
    spinlock_t lock;
};

Members

net

struct net

node

TIPC node (RX)

aead

array of pointers to AEAD keys for encryption/decryption

peer_rx_active

replicated peer RX active key index

key_gen

TX/RX key generation

key

the key states

skey_mode

session key's mode

skey

received session key

wq

common workqueue on TX crypto

work

delayed work sched for TX/RX

key_distr

key distributing state

rekeying_intv

rekeying interval (in minutes)

stats

the crypto statistics

name

the crypto name

sndnxt

the per-peer sndnxt (TX)

timer1

general timer 1 (jiffies)

timer2

general timer 2 (jiffies)

{unnamed_union}

anonymous

{unnamed_struct}

anonymous

working

the crypto is working or not

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

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

Validate a AEAD user key

Parameters

struct tipc_aead_key *ukey

pointer to user key data

struct genl_info *info

netlink info pointer

int tipc_aead_key_generate(struct tipc_aead_key *skey)

Generate new session key

Parameters

struct tipc_aead_key *skey

input/output key with new content

Return

0 in case of success, otherwise < 0

void tipc_aead_free(struct rcu_head *rp)

Release AEAD key incl. all the TFMs in the list

Parameters

struct rcu_head *rp

rcu head pointer

struct crypto_aead *tipc_aead_tfm_next(struct tipc_aead *aead)

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

Parameters

struct tipc_aead *aead

the AEAD key pointer

int tipc_aead_init(struct tipc_aead **aead, struct tipc_aead_key *ukey, u8 mode)

Initiate TIPC AEAD

Parameters

struct tipc_aead **aead

returned new TIPC AEAD key handle pointer

struct tipc_aead_key *ukey

pointer to user key data

u8 mode

the key mode

Description

Allocate a (list of) new cipher transformation (TFM) with the specific user key data if valid. The number of the allocated TFMs can be set via the sysfs "net/tipc/max_tfms" first. Also, all the other AEAD data are also initialized.

Return

0 if the initiation is successful, otherwise: < 0

int tipc_aead_clone(struct tipc_aead **dst, struct tipc_aead *src)

Clone a TIPC AEAD key

Parameters

struct tipc_aead **dst

dest key for the cloning

struct tipc_aead *src

source key to clone from

Description

Make a "copy" of the source AEAD key data to the dest, the TFMs list is common for the keys. A reference to the source is hold in the "cloned" pointer for the later freeing purposes.

Note

this must be done in cluster-key mode only!

Return

0 in case of success, otherwise < 0

void *tipc_aead_mem_alloc(struct crypto_aead *tfm, unsigned int crypto_ctx_size, u8 **iv, struct aead_request **req, struct scatterlist **sg, int nsg)

Allocate memory for AEAD request operations

Parameters

struct crypto_aead *tfm

cipher handle to be registered with the request

unsigned int crypto_ctx_size

size of crypto context for callback

u8 **iv

returned pointer to IV data

struct aead_request **req

returned pointer to AEAD request data

struct scatterlist **sg

returned pointer to SG lists

int nsg

number of SG lists to be allocated

Description

Allocate memory to store the crypto context data, AEAD request, IV and SG lists, the memory layout is as follows: crypto_ctx || iv || aead_req || sg[]

Return

the pointer to the memory areas in case of success, otherwise NULL

int tipc_aead_encrypt(struct tipc_aead *aead, struct sk_buff *skb, struct tipc_bearer *b, struct tipc_media_addr *dst, struct tipc_node *__dnode)

Encrypt a message

Parameters

struct tipc_aead *aead

TIPC AEAD key for the message encryption

struct sk_buff *skb

the input/output skb

struct tipc_bearer *b

TIPC bearer where the message will be delivered after the encryption

struct tipc_media_addr *dst

the destination media address

struct tipc_node *__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

int tipc_aead_decrypt(struct net *net, struct tipc_aead *aead, struct sk_buff *skb, struct tipc_bearer *b)

Decrypt an encrypted message

Parameters

struct net *net

struct net

struct tipc_aead *aead

TIPC AEAD for the message decryption

struct sk_buff *skb

the input/output skb

struct tipc_bearer *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

bool tipc_ehdr_validate(struct sk_buff *skb)

Validate an encryption message

Parameters

struct sk_buff *skb

the message buffer

Return

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

int tipc_ehdr_build(struct net *net, struct tipc_aead *aead, u8 tx_key, struct sk_buff *skb, struct tipc_crypto *__rx)

Build TIPC encryption message header

Parameters

struct net *net

struct net

struct tipc_aead *aead

TX AEAD key to be used for the message encryption

u8 tx_key

key id used for the message encryption

struct sk_buff *skb

input/output message skb

struct tipc_crypto *__rx

RX crypto handle if dest is "known"

Return

the header size if the building is successful, otherwise < 0

int tipc_crypto_key_init(struct tipc_crypto *c, struct tipc_aead_key *ukey, u8 mode, bool master_key)

Initiate a new user / AEAD key

Parameters

struct tipc_crypto *c

TIPC crypto to which new key is attached

struct tipc_aead_key *ukey

the user key

u8 mode

the key mode (CLUSTER_KEY or PER_NODE_KEY)

bool master_key

specify this is a cluster master key

Description

A new TIPC AEAD key will be allocated and initiated with the specified user key, then attached to the TIPC crypto.

Return

new key id in case of success, otherwise: < 0

int tipc_crypto_key_attach(struct tipc_crypto *c, struct tipc_aead *aead, u8 pos, bool master_key)

Attach a new AEAD key to TIPC crypto

Parameters

struct tipc_crypto *c

TIPC crypto to which the new AEAD key is attached

struct tipc_aead *aead

the new AEAD key pointer

u8 pos

desired slot in the crypto key array, = 0 if any!

bool master_key

specify this is a cluster master key

Return

new key id in case of success, otherwise: -EBUSY

bool tipc_crypto_key_try_align(struct tipc_crypto *rx, u8 new_pending)

Align RX keys if possible

Parameters

struct tipc_crypto *rx

RX crypto handle

u8 new_pending

new pending slot if aligned (= TX key from peer)

Description

Peer has used an unknown key slot, this only happens when peer has left and rejoned, or we are newcomer. That means, there must be no active key but a pending key at unaligned slot. If so, we try to move the pending key to the new slot.

Note

A potential passive key can exist, it will be shifted correspondingly!

Return

"true" if key is successfully aligned, otherwise "false"

struct tipc_aead *tipc_crypto_key_pick_tx(struct tipc_crypto *tx, struct tipc_crypto *rx, struct sk_buff *skb, u8 tx_key)

Pick one TX key for message decryption

Parameters

struct tipc_crypto *tx

TX crypto handle

struct tipc_crypto *rx

RX crypto handle (can be NULL)

struct sk_buff *skb

the message skb which will be decrypted later

u8 tx_key

peer TX key id

Description

This function looks up the existing TX keys and pick one which is suitable for the message decryption, that must be a cluster key and not used before on the same message (i.e. recursive).

Return

the TX AEAD key handle in case of success, otherwise NULL

void tipc_crypto_key_synch(struct tipc_crypto *rx, struct sk_buff *skb)

Synch own key data according to peer key status

Parameters

struct tipc_crypto *rx

RX crypto handle

struct sk_buff *skb

TIPCv2 message buffer (incl. the ehdr from peer)

Description

This function updates the peer node related data as the peer RX active key has changed, so the number of TX keys' users on this node are increased and decreased correspondingly.

It also considers if peer has no key, then we need to make own master key (if any) taking over i.e. starting grace period and also trigger key distributing process.

The "per-peer" sndnxt is also reset when the peer key has switched.

int tipc_crypto_xmit(struct net *net, struct sk_buff **skb, struct tipc_bearer *b, struct tipc_media_addr *dst, struct tipc_node *__dnode)

Build & encrypt TIPC message for xmit

Parameters

struct net *net

struct net

struct sk_buff **skb

input/output message skb pointer

struct tipc_bearer *b

bearer used for xmit later

struct tipc_media_addr *dst

destination media address

struct tipc_node *__dnode

destination node for reference if any

Description

First, build an encryption message header on the top of the message, then encrypt the original TIPC message by using the pending, master or active key with this preference order. If the encryption is successful, the encrypted skb is returned directly or via the callback. 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

int tipc_crypto_rcv(struct net *net, struct tipc_crypto *rx, struct sk_buff **skb, struct tipc_bearer *b)

Decrypt an encrypted TIPC message from peer

Parameters

struct net *net

struct net

struct tipc_crypto *rx

RX crypto handle

struct sk_buff **skb

input/output message skb pointer

struct tipc_bearer *b

bearer where the message has been received

Description

If the decryption is successful, the decrypted skb is returned directly or as the callback, the encryption header and auth tag will be trimed out before forwarding to tipc_rcv() via the tipc_crypto_rcv_complete(). Otherwise, the skb will be freed!

Note

RX key(s) can be re-aligned, or in case of no key suitable, TX 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

void tipc_crypto_msg_rcv(struct net *net, struct sk_buff *skb)

Common 'MSG_CRYPTO' processing point

Parameters

struct net *net

the struct net

struct sk_buff *skb

the receiving message buffer

int tipc_crypto_key_distr(struct tipc_crypto *tx, u8 key, struct tipc_node *dest)

Distribute a TX key

Parameters

struct tipc_crypto *tx

the TX crypto

u8 key

the key's index

struct tipc_node *dest

the destination tipc node, = NULL if distributing to all nodes

Return

0 in case of success, otherwise < 0

int tipc_crypto_key_xmit(struct net *net, struct tipc_aead_key *skey, u16 gen, u8 mode, u32 dnode)

Send a session key

Parameters

struct net *net

the struct net

struct tipc_aead_key *skey

the session key to be sent

u16 gen

the key's generation

u8 mode

the key's mode

u32 dnode

the destination node address, = 0 if broadcasting to all nodes

Description

The session key 'skey' is packed in a TIPC v2 'MSG_CRYPTO/KEY_DISTR_MSG' as its data section, then xmit-ed through the uc/bc link.

Return

0 in case of success, otherwise < 0

bool tipc_crypto_key_rcv(struct tipc_crypto *rx, struct tipc_msg *hdr)

Receive a session key

Parameters

struct tipc_crypto *rx

the RX crypto

struct tipc_msg *hdr

the TIPC v2 message incl. the receiving session key in its data

Description

This function retrieves the session key in the message from peer, then schedules a RX work to attach the key to the corresponding RX crypto.

Return

"true" if the key has been scheduled for attaching, otherwise "false".

void tipc_crypto_work_rx(struct work_struct *work)

Scheduled RX works handler

Parameters

struct work_struct *work

the struct RX work

Description

The function processes the previous scheduled works i.e. distributing TX key or attaching a received session key on RX crypto.

void tipc_crypto_rekeying_sched(struct tipc_crypto *tx, bool changed, u32 new_intv)

(Re)schedule rekeying w/o new interval

Parameters

struct tipc_crypto *tx

TX crypto

bool changed

if the rekeying needs to be rescheduled with new interval

u32 new_intv

new rekeying interval (when "changed" = true)

void tipc_crypto_work_tx(struct work_struct *work)

Scheduled TX works handler

Parameters

struct work_struct *work

the struct TX work

Description

The function processes the previous scheduled work, i.e. key rekeying, by generating a new session key based on current one, then attaching it to the TX crypto and finally distributing it to peers. It also re-schedules the rekeying if needed.

TIPC Discoverer Interfaces

struct tipc_discoverer

information about an ongoing link setup request

Definition:

struct tipc_discoverer {
    u32 bearer_id;
    struct tipc_media_addr dest;
    struct net *net;
    u32 domain;
    int num_nodes;
    spinlock_t lock;
    struct sk_buff *skb;
    struct timer_list timer;
    unsigned long timer_intv;
};

Members

bearer_id

identity of bearer issuing requests

dest

destination address for request messages

net

network namespace instance

domain

network domain to which links can be established

num_nodes

number of nodes currently discovered (i.e. with an active link)

lock

spinlock for controlling access to requests

skb

request message to be (repeatedly) sent

timer

timer governing period between requests

timer_intv

current interval between requests (in ms)

void tipc_disc_init_msg(struct net *net, struct sk_buff *skb, u32 mtyp, struct tipc_bearer *b)

initialize a link setup message

Parameters

struct net *net

the applicable net namespace

struct sk_buff *skb

buffer containing message

u32 mtyp

message type (request or response)

struct tipc_bearer *b

ptr to bearer issuing message

void disc_dupl_alert(struct tipc_bearer *b, u32 node_addr, struct tipc_media_addr *media_addr)

issue node address duplication alert

Parameters

struct tipc_bearer *b

pointer to bearer detecting duplication

u32 node_addr

duplicated node address

struct tipc_media_addr *media_addr

media address advertised by duplicated node

void tipc_disc_rcv(struct net *net, struct sk_buff *skb, struct tipc_bearer *b)

handle incoming discovery message (request or response)

Parameters

struct net *net

applicable net namespace

struct sk_buff *skb

buffer containing message

struct tipc_bearer *b

bearer that message arrived on

int tipc_disc_create(struct net *net, struct tipc_bearer *b, struct tipc_media_addr *dest, struct sk_buff **skb)

create object to send periodic link setup requests

Parameters

struct net *net

the applicable net namespace

struct tipc_bearer *b

ptr to bearer issuing requests

struct tipc_media_addr *dest

destination address for request messages

struct sk_buff **skb

pointer to created frame

Return

0 if successful, otherwise -errno.

void tipc_disc_delete(struct tipc_discoverer *d)

destroy object sending periodic link setup requests

Parameters

struct tipc_discoverer *d

ptr to link dest structure

void tipc_disc_reset(struct net *net, struct tipc_bearer *b)

reset object to send periodic link setup requests

Parameters

struct net *net

the applicable net namespace

struct tipc_bearer *b

ptr to bearer issuing requests

TIPC msg Interfaces

struct sk_buff *tipc_buf_acquire(u32 size, gfp_t gfp)

creates a TIPC message buffer

Parameters

u32 size

message size (including TIPC header)

gfp_t gfp

memory allocation flags

Return

a new buffer with data pointers set to the specified size.

NOTE

Headroom is reserved to allow prepending of a data link header. There may also be unrequested tailroom present at the buffer's end.

int tipc_msg_append(struct tipc_msg *_hdr, struct msghdr *m, int dlen, int mss, struct sk_buff_head *txq)

Append data to tail of an existing buffer queue

Parameters

struct tipc_msg *_hdr

header to be used

struct msghdr *m

the data to be appended

int dlen

size of data to be appended

int mss

max allowable size of buffer

struct sk_buff_head *txq

queue to append to

Return

the number of 1k blocks appended or errno value

int tipc_msg_fragment(struct sk_buff *skb, const struct tipc_msg *hdr, int pktmax, struct sk_buff_head *frags)

build a fragment skb list for TIPC message

Parameters

struct sk_buff *skb

TIPC message skb

const struct tipc_msg *hdr

internal msg header to be put on the top of the fragments

int pktmax

max size of a fragment incl. the header

struct sk_buff_head *frags

returned fragment skb list

Return

0 if the fragmentation is successful, otherwise: -EINVAL or -ENOMEM

int tipc_msg_build(struct tipc_msg *mhdr, struct msghdr *m, int offset, int dsz, int pktmax, struct sk_buff_head *list)

create buffer chain containing specified header and data

Parameters

struct tipc_msg *mhdr

Message header, to be prepended to data

struct msghdr *m

User message

int offset

buffer offset for fragmented messages (FIXME)

int dsz

Total length of user data

int pktmax

Max packet size that can be used

struct sk_buff_head *list

Buffer or chain of buffers to be returned to caller

Description

Note that the recursive call we are making here is safe, since it can logically go only one further level down.

Return

message data size or errno: -ENOMEM, -EFAULT

bool tipc_msg_bundle(struct sk_buff *bskb, struct tipc_msg *msg, u32 max)

Append contents of a buffer to tail of an existing one

Parameters

struct sk_buff *bskb

the bundle buffer to append to

struct tipc_msg *msg

message to be appended

u32 max

max allowable size for the bundle buffer

Return

"true" if bundling has been performed, otherwise "false"

bool tipc_msg_try_bundle(struct sk_buff *tskb, struct sk_buff **skb, u32 mss, u32 dnode, bool *new_bundle)

Try to bundle a new message to the last one

Parameters

struct sk_buff *tskb

the last/target message to which the new one will be appended

struct sk_buff **skb

the new message skb pointer

u32 mss

max message size (header inclusive)

u32 dnode

destination node for the message

bool *new_bundle

if this call made a new bundle or not

Return

"true" if the new message skb is potential for bundling this time or later, in the case a bundling has been done this time, the skb is consumed (the skb pointer = NULL). Otherwise, "false" if the skb cannot be bundled at all.

bool tipc_msg_extract(struct sk_buff *skb, struct sk_buff **iskb, int *pos)

extract bundled inner packet from buffer

Parameters

struct sk_buff *skb

buffer to be extracted from.

struct sk_buff **iskb

extracted inner buffer, to be returned

int *pos

position in outer message of msg to be extracted. Returns position of next msg. Consumes outer buffer when last packet extracted

Return

true when there is an extracted buffer, otherwise false

bool tipc_msg_reverse(u32 own_node, struct sk_buff **skb, int err)

swap source and destination addresses and add error code

Parameters

u32 own_node

originating node id for reversed message

struct sk_buff **skb

buffer containing message to be reversed; will be consumed

int err

error code to be set in message, if any Replaces consumed buffer with new one when successful

Return

true if success, otherwise false

bool tipc_msg_lookup_dest(struct net *net, struct sk_buff *skb, int *err)

try to find new destination for named message

Parameters

struct net *net

pointer to associated network namespace

struct sk_buff *skb

the buffer containing the message.

int *err

error code to be used by caller if lookup fails Does not consume buffer

Return

true if a destination is found, false otherwise

TIPC Name Interfaces

struct service_range

container for all bindings of a service range

Definition:

struct service_range {
    u32 lower;
    u32 upper;
    struct rb_node tree_node;
    u32 max;
    struct list_head local_publ;
    struct list_head all_publ;
};

Members

lower

service range lower bound

upper

service range upper bound

tree_node

member of service range RB tree

max

largest 'upper' in this node subtree

local_publ

list of identical publications made from this node Used by closest_first lookup and multicast lookup algorithm

all_publ

all publications identical to this one, whatever node and scope Used by round-robin lookup algorithm

struct tipc_service

container for all published instances of a service type

Definition:

struct tipc_service {
    u32 type;
    u32 publ_cnt;
    struct rb_root ranges;
    struct hlist_node service_list;
    struct list_head subscriptions;
    spinlock_t lock;
    struct rcu_head rcu;
};

Members

type

32 bit 'type' value for service

publ_cnt

increasing counter for publications in this service

ranges

rb tree containing all service ranges for this service

service_list

links to adjacent name ranges in hash chain

subscriptions

list of subscriptions for this service type

lock

spinlock controlling access to pertaining service ranges/publications

rcu

RCU callback head used for deferred freeing

service_range_foreach_match

service_range_foreach_match (sr, sc, start, end)

iterate over tipc service rbtree for each range match

Parameters

sr

the service range pointer as a loop cursor

sc

the pointer to tipc service which holds the service range rbtree

start

beginning of the search range (end >= start) for matching

end

end of the search range (end >= start) for matching

struct service_range *service_range_match_first(struct rb_node *n, u32 start, u32 end)

find first service range matching a range

Parameters

struct rb_node *n

the root node of service range rbtree for searching

u32 start

beginning of the search range (end >= start) for matching

u32 end

end of the search range (end >= start) for matching

Return

the leftmost service range node in the rbtree that overlaps the specific range if any. Otherwise, returns NULL.

struct service_range *service_range_match_next(struct rb_node *n, u32 start, u32 end)

find next service range matching a range

Parameters

struct rb_node *n

a node in service range rbtree from which the searching starts

u32 start

beginning of the search range (end >= start) for matching

u32 end

end of the search range (end >= start) for matching

Return

the next service range node to the given node in the rbtree that overlaps the specific range if any. Otherwise, returns NULL.

struct publication *tipc_publ_create(struct tipc_uaddr *ua, struct tipc_socket_addr *sk, u32 key)

create a publication structure

Parameters

struct tipc_uaddr *ua

the service range the user is binding to

struct tipc_socket_addr *sk

the address of the socket that is bound

u32 key

publication key

struct tipc_service *tipc_service_create(struct net *net, struct tipc_uaddr *ua)

create a service structure for the specified 'type'

Parameters

struct net *net

network namespace

struct tipc_uaddr *ua

address representing the service to be bound

Description

Allocates a single range structure and sets it to all 0's.

struct publication *tipc_service_remove_publ(struct service_range *r, struct tipc_socket_addr *sk, u32 key)

remove a publication from a service

Parameters

struct service_range *r

service_range to remove publication from

struct tipc_socket_addr *sk

address publishing socket

u32 key

target publication key

void tipc_service_subscribe(struct tipc_service *service, struct tipc_subscription *sub)

attach a subscription, and optionally issue the prescribed number of events if there is any service range overlapping with the requested range

Parameters

struct tipc_service *service

the tipc_service to attach the sub to

struct tipc_subscription *sub

the subscription to attach

bool tipc_nametbl_lookup_anycast(struct net *net, struct tipc_uaddr *ua, struct tipc_socket_addr *sk)

perform service instance to socket translation

Parameters

struct net *net

network namespace

struct tipc_uaddr *ua

service address to look up

struct tipc_socket_addr *sk

address to socket we want to find

Description

On entry, a non-zero 'sk->node' indicates the node where we want lookup to be performed, which may not be this one.

On exit:

  • If lookup is deferred to another node, leave 'sk->node' unchanged and return 'true'.

  • If lookup is successful, set the 'sk->node' and 'sk->ref' (== portid) which represent the bound socket and return 'true'.

  • If lookup fails, return 'false'

Note that for legacy users (node configured with Z.C.N address format) the 'closest-first' lookup algorithm must be maintained, i.e., if sk.node is 0 we must look in the local binding list first

void tipc_nametbl_withdraw(struct net *net, struct tipc_uaddr *ua, struct tipc_socket_addr *sk, u32 key)

withdraw a service binding

Parameters

struct net *net

network namespace

struct tipc_uaddr *ua

service address/range being unbound

struct tipc_socket_addr *sk

address of the socket being unbound from

u32 key

target publication key

bool tipc_nametbl_subscribe(struct tipc_subscription *sub)

add a subscription object to the name table

Parameters

struct tipc_subscription *sub

subscription to add

void tipc_nametbl_unsubscribe(struct tipc_subscription *sub)

remove a subscription object from name table

Parameters

struct tipc_subscription *sub

subscription to remove

void tipc_service_delete(struct net *net, struct tipc_service *sc)

purge all publications for a service and delete it

Parameters

struct net *net

the associated network namespace

struct tipc_service *sc

tipc_service to delete

void publ_to_item(struct distr_item *i, struct publication *p)

add publication info to a publication message

Parameters

struct distr_item *i

location of item in the message

struct publication *p

publication info

struct sk_buff *named_prepare_buf(struct net *net, u32 type, u32 size, u32 dest)

allocate & initialize a publication message

Parameters

struct net *net

the associated network namespace

u32 type

message type

u32 size

payload size

u32 dest

destination node

Description

The buffer returned is of size INT_H_SIZE + payload size

struct sk_buff *tipc_named_publish(struct net *net, struct publication *p)

tell other nodes about a new publication by this node

Parameters

struct net *net

the associated network namespace

struct publication *p

the new publication

struct sk_buff *tipc_named_withdraw(struct net *net, struct publication *p)

tell other nodes about a withdrawn publication by this node

Parameters

struct net *net

the associated network namespace

struct publication *p

the withdrawn publication

void named_distribute(struct net *net, struct sk_buff_head *list, u32 dnode, struct list_head *pls, u16 seqno)

prepare name info for bulk distribution to another node

Parameters

struct net *net

the associated network namespace

struct sk_buff_head *list

list of messages (buffers) to be returned from this function

u32 dnode

node to be updated

struct list_head *pls

linked list of publication items to be packed into buffer chain

u16 seqno

sequence number for this message

void tipc_named_node_up(struct net *net, u32 dnode, u16 capabilities)

tell specified node about all publications by this node

Parameters

struct net *net

the associated network namespace

u32 dnode

destination node

u16 capabilities

peer node's capabilities

void tipc_publ_purge(struct net *net, struct publication *p, u32 addr)

remove publication associated with a failed node

Parameters

struct net *net

the associated network namespace

struct publication *p

the publication to remove

u32 addr

failed node's address

Description

Invoked for each publication issued by a newly failed node. Removes publication structure from name table & deletes it.

bool tipc_update_nametbl(struct net *net, struct distr_item *i, u32 node, u32 dtype)

try to process a nametable update and notify subscribers

Parameters

struct net *net

the associated network namespace

struct distr_item *i

location of item in the message

u32 node

node address

u32 dtype

name distributor message type

Description

tipc_nametbl_lock must be held.

Return

the publication item if successful, otherwise NULL.

void tipc_named_rcv(struct net *net, struct sk_buff_head *namedq, u16 *rcv_nxt, bool *open)

process name table update messages sent by another node

Parameters

struct net *net

the associated network namespace

struct sk_buff_head *namedq

queue to receive from

u16 *rcv_nxt

store last received seqno here

bool *open

last bulk msg was received (FIXME)

void tipc_named_reinit(struct net *net)

re-initialize local publications

Parameters

struct net *net

the associated network namespace

Description

This routine is called whenever TIPC networking is enabled. All name table entries published by this node are updated to reflect the node's new network address.

TIPC Node Management Interfaces

struct tipc_node

TIPC node structure

Definition:

struct tipc_node {
    u32 addr;
    struct kref kref;
    rwlock_t lock;
    struct net *net;
    struct hlist_node hash;
    int active_links[2];
    struct tipc_link_entry links[MAX_BEARERS];
    struct tipc_bclink_entry bc_entry;
    int action_flags;
    struct list_head list;
    int state;
    bool preliminary;
    bool failover_sent;
    u16 sync_point;
    int link_cnt;
    u16 working_links;
    u16 capabilities;
    u32 signature;
    u32 link_id;
    u8 peer_id[16];
    char peer_id_string[NODE_ID_STR_LEN];
    struct list_head publ_list;
    struct list_head conn_sks;
    unsigned long keepalive_intv;
    struct timer_list timer;
    struct rcu_head rcu;
    unsigned long delete_at;
    struct net *peer_net;
    u32 peer_hash_mix;
#ifdef CONFIG_TIPC_CRYPTO;
    struct tipc_crypto *crypto_rx;
#endif;
};

Members

addr

network address of node

kref

reference counter to node object

lock

rwlock governing access to structure

net

the applicable net namespace

hash

links to adjacent nodes in unsorted hash chain

active_links

bearer ids of active links, used as index into links[] array

links

array containing references to all links to node

bc_entry

broadcast link entry

action_flags

bit mask of different types of node actions

list

links to adjacent nodes in sorted list of cluster's nodes

state

connectivity state vs peer node

preliminary

a preliminary node or not

failover_sent

failover sent or not

sync_point

sequence number where synch/failover is finished

link_cnt

number of links to node

working_links

number of working links to node (both active and standby)

capabilities

bitmap, indicating peer node's functional capabilities

signature

node instance identifier

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

conn_sks

list of connections (FIXME)

keepalive_intv

keepalive interval in milliseconds

timer

node's keepalive timer

rcu

rcu struct for tipc_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

struct tipc_crypto *tipc_node_crypto_rx(struct tipc_node *__n)

Retrieve crypto RX handle from node

Parameters

struct tipc_node *__n

target tipc_node

Note

node ref counter must be held first!

handle addition of link

Parameters

struct tipc_node *n

target tipc_node

int bearer_id

id of the bearer

struct sk_buff_head *xmitq

queue for messages to be xmited on Node lock must be held by caller Link becomes active (alone or shared) or standby, depending on its priority.

handle addition of link

Parameters

struct tipc_node *n

target tipc_node

int bearer_id

id of the bearer

struct sk_buff_head *xmitq

queue for messages to be xmited on

Description

Link becomes active (alone or shared) or standby, depending on its priority.

start failover in case "half-failover"

Parameters

struct tipc_node *n

tipc node structure

struct tipc_link *l

link peer endpoint failingover (- can be NULL)

struct tipc_link *tnl

tunnel link

struct sk_buff_head *xmitq

queue for messages to be xmited on tnl link later

Description

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. This can happen when e.g.:

1. Both links <1A-2A>, <1B-2B> down
2. Link endpoint 2A up, but 1A still down (e.g. due to network
disturbance, wrong session, etc.)
3. Link <1B-2B> up
4. Link endpoint 2A down (e.g. due to link tolerance timeout)
5. Node 2 starts failover onto link <1B-2B>

==> Node 1 does never start link/node failover!

handle loss of link

Parameters

struct tipc_node *n

target tipc_node

int *bearer_id

id of the bearer

struct sk_buff_head *xmitq

queue for messages to be xmited on

struct tipc_media_addr **maddr

output media address of the bearer

int tipc_node_get_linkname(struct net *net, u32 bearer_id, u32 addr, char *linkname, size_t len)

get the name of a link

Parameters

struct net *net

the applicable net namespace

u32 bearer_id

id of the bearer

u32 addr

peer node address

char *linkname

link name output buffer

size_t len

size of linkname output buffer

Return

0 on success

int tipc_node_xmit(struct net *net, struct sk_buff_head *list, u32 dnode, int selector)

general link level function for message sending

Parameters

struct net *net

the applicable net namespace

struct sk_buff_head *list

chain of buffers containing message

u32 dnode

address of destination node

int selector

a number used for deterministic link selection Consumes the buffer chain.

Return

0 if success, otherwise: -ELINKCONG,-EHOSTUNREACH,-EMSGSIZE,-ENOBUF

void tipc_node_bc_rcv(struct net *net, struct sk_buff *skb, int bearer_id)

process TIPC broadcast packet arriving from off-node

Parameters

struct net *net

the applicable net namespace

struct sk_buff *skb

TIPC packet

int bearer_id

id of bearer message arrived on

Description

Invoked with no locks held.

bool tipc_node_check_state(struct tipc_node *n, struct sk_buff *skb, int bearer_id, struct sk_buff_head *xmitq)

check and if necessary update node state

Parameters

struct tipc_node *n

target tipc_node

struct sk_buff *skb

TIPC packet

int bearer_id

identity of bearer delivering the packet

struct sk_buff_head *xmitq

queue for messages to be xmited on

Return

true if state and msg are ok, otherwise false

void tipc_rcv(struct net *net, struct sk_buff *skb, struct tipc_bearer *b)

process TIPC packets/messages arriving from off-node

Parameters

struct net *net

the applicable net namespace

struct sk_buff *skb

TIPC packet

struct tipc_bearer *b

pointer to bearer message arrived on

Description

Invoked with no locks held. Bearer pointer must point to a valid bearer structure (i.e. cannot be NULL), but bearer can be inactive.

int tipc_node_dump(struct tipc_node *n, bool more, char *buf)

dump TIPC node data

Parameters

struct tipc_node *n

tipc node to be dumped

bool more

dump more? - false: dump only tipc node data - true: dump node link data as well

char *buf

returned buffer of dump data in format

TIPC Socket Interfaces

struct tipc_sock

TIPC socket structure

Definition:

struct tipc_sock {
    struct sock sk;
    u32 max_pkt;
    u32 maxnagle;
    u32 portid;
    struct tipc_msg phdr;
    struct list_head cong_links;
    struct list_head publications;
    u32 pub_count;
    atomic_t dupl_rcvcnt;
    u16 conn_timeout;
    bool probe_unacked;
    u16 cong_link_cnt;
    u16 snt_unacked;
    u16 snd_win;
    u16 peer_caps;
    u16 rcv_unacked;
    u16 rcv_win;
    struct sockaddr_tipc peer;
    struct rhash_head node;
    struct tipc_mc_method mc_method;
    struct rcu_head rcu;
    struct tipc_group *group;
    u32 oneway;
    u32 nagle_start;
    u16 snd_backlog;
    u16 msg_acc;
    u16 pkt_cnt;
    bool expect_ack;
    bool nodelay;
    bool group_is_open;
    bool published;
    u8 conn_addrtype;
};

Members

sk

socket - interacts with 'port' and with user via the socket API

max_pkt

maximum packet size "hint" used when building messages sent by port

maxnagle

maximum size of msg which can be subject to nagle

portid

unique port identity in TIPC socket hash table

phdr

preformatted message header used when sending messages

cong_links

list of congested links

publications

list of publications for port

pub_count

total # of publications port has made during its lifetime

dupl_rcvcnt

number of bytes counted twice, in both backlog and rcv queue

conn_timeout

the time we can wait for an unresponded setup request

probe_unacked

probe has not received ack yet

cong_link_cnt

number of congested links

snt_unacked

# messages sent by socket, and not yet acked by peer

snd_win

send window size

peer_caps

peer capabilities mask

rcv_unacked

# messages read by user, but not yet acked back to peer

rcv_win

receive window size

peer

'connected' peer for dgram/rdm

node

hash table node

mc_method

cookie for use between socket and broadcast layer

rcu

rcu struct for tipc_sock

group

TIPC communications group

oneway

message count in one direction (FIXME)

nagle_start

current nagle value

snd_backlog

send backlog count

msg_acc

messages accepted; used in managing backlog and nagle

pkt_cnt

TIPC socket packet count

expect_ack

whether this TIPC socket is expecting an ack

nodelay

setsockopt() TIPC_NODELAY setting

group_is_open

TIPC socket group is fully open (FIXME)

published

true if port has one or more associated names

conn_addrtype

address type used when establishing connection

void tsk_advance_rx_queue(struct sock *sk)

discard first buffer in socket receive queue

Parameters

struct sock *sk

network socket

Description

Caller must hold socket lock

void tsk_rej_rx_queue(struct sock *sk, int error)

reject all buffers in socket receive queue

Parameters

struct sock *sk

network socket

int error

response error code

Description

Caller must hold socket lock

int tipc_sk_create(struct net *net, struct socket *sock, int protocol, int kern)

create a TIPC socket

Parameters

struct net *net

network namespace (must be default network)

struct socket *sock

pre-allocated socket structure

int protocol

protocol indicator (must be 0)

int kern

caused by kernel or by userspace?

Description

This routine creates additional data structures used by the TIPC socket, initializes them, and links them together.

Return

0 on success, errno otherwise

int tipc_release(struct socket *sock)

destroy a TIPC socket

Parameters

struct socket *sock

socket to destroy

Description

This routine cleans up any messages that are still queued on the socket. For DGRAM and RDM socket types, all queued messages are rejected. For SEQPACKET and STREAM socket types, the first message is rejected and any others are discarded. (If the first message on a STREAM socket is partially-read, it is discarded and the next one is rejected instead.)

NOTE

Rejected messages are not necessarily returned to the sender! They are returned or discarded according to the "destination droppable" setting specified for the message by the sender.

Return

0 on success, errno otherwise

int __tipc_bind(struct socket *sock, struct sockaddr *skaddr, int alen)

associate or disassocate TIPC name(s) with a socket

Parameters

struct socket *sock

socket structure

struct sockaddr *skaddr

socket address describing name(s) and desired operation

int alen

size of socket address data structure

Description

Name and name sequence binding are indicated using a positive scope value; a negative scope value unbinds the specified name. Specifying no name (i.e. a socket address length of 0) unbinds all names from the socket.

Return

0 on success, errno otherwise

NOTE

This routine doesn't need to take the socket lock since it doesn't

access any non-constant socket information.

int tipc_getname(struct socket *sock, struct sockaddr *uaddr, int peer)

get port ID of socket or peer socket

Parameters

struct socket *sock

socket structure

struct sockaddr *uaddr

area for returned socket address

int peer

0 = own ID, 1 = current peer ID, 2 = current/former peer ID

Return

0 on success, errno otherwise

NOTE

This routine doesn't need to take the socket lock since it only

accesses socket information that is unchanging (or which changes in a completely predictable manner).

__poll_t tipc_poll(struct file *file, struct socket *sock, poll_table *wait)

read and possibly block on pollmask

Parameters

struct file *file

file structure associated with the socket

struct socket *sock

socket for which to calculate the poll bits

poll_table *wait

???

Return

pollmask value

Description

COMMENTARY: It appears that the usual socket locking mechanisms are not useful here since the pollmask info is potentially out-of-date the moment this routine exits. TCP and other protocols seem to rely on higher level poll routines to handle any preventable race conditions, so TIPC will do the same ...

IMPORTANT: The fact that a read or write operation is indicated does NOT imply that the operation will succeed, merely that it should be performed and will not block.

int tipc_sendmcast(struct socket *sock, struct tipc_uaddr *ua, struct msghdr *msg, size_t dlen, long timeout)

send multicast message

Parameters

struct socket *sock

socket structure

struct tipc_uaddr *ua

destination address struct

struct msghdr *msg

message to send

size_t dlen

length of data to send

long timeout

timeout to wait for wakeup

Description

Called from function tipc_sendmsg(), which has done all sanity checks

Return

the number of bytes sent on success, or errno

int tipc_send_group_msg(struct net *net, struct tipc_sock *tsk, struct msghdr *m, struct tipc_member *mb, u32 dnode, u32 dport, int dlen)

send a message to a member in the group

Parameters

struct net *net

network namespace

struct tipc_sock *tsk

tipc socket

struct msghdr *m

message to send

struct tipc_member *mb

group member

u32 dnode

destination node

u32 dport

destination port

int dlen

total length of message data

int tipc_send_group_unicast(struct socket *sock, struct msghdr *m, int dlen, long timeout)

send message to a member in the group

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

int dlen

total length of message data

long timeout

timeout to wait for wakeup

Description

Called from function tipc_sendmsg(), which has done all sanity checks

Return

the number of bytes sent on success, or errno

int tipc_send_group_anycast(struct socket *sock, struct msghdr *m, int dlen, long timeout)

send message to any member with given identity

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

int dlen

total length of message data

long timeout

timeout to wait for wakeup

Description

Called from function tipc_sendmsg(), which has done all sanity checks

Return

the number of bytes sent on success, or errno

int tipc_send_group_bcast(struct socket *sock, struct msghdr *m, int dlen, long timeout)

send message to all members in communication group

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

int dlen

total length of message data

long timeout

timeout to wait for wakeup

Description

Called from function tipc_sendmsg(), which has done all sanity checks

Return

the number of bytes sent on success, or errno

int tipc_send_group_mcast(struct socket *sock, struct msghdr *m, int dlen, long timeout)

send message to all members with given identity

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

int dlen

total length of message data

long timeout

timeout to wait for wakeup

Description

Called from function tipc_sendmsg(), which has done all sanity checks

Return

the number of bytes sent on success, or errno

void tipc_sk_mcast_rcv(struct net *net, struct sk_buff_head *arrvq, struct sk_buff_head *inputq)

Deliver multicast messages to all destination sockets

Parameters

struct net *net

the associated network namespace

struct sk_buff_head *arrvq

queue with arriving messages, to be cloned after destination lookup

struct sk_buff_head *inputq

queue with cloned messages, delivered to socket after dest lookup

Description

Multi-threaded: parallel calls with reference to same queues may occur

void tipc_sk_conn_proto_rcv(struct tipc_sock *tsk, struct sk_buff *skb, struct sk_buff_head *inputq, struct sk_buff_head *xmitq)

receive a connection mng protocol message

Parameters

struct tipc_sock *tsk

receiving socket

struct sk_buff *skb

pointer to message buffer.

struct sk_buff_head *inputq

buffer list containing the buffers

struct sk_buff_head *xmitq

output message area

int tipc_sendmsg(struct socket *sock, struct msghdr *m, size_t dsz)

send message in connectionless manner

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

size_t dsz

amount of user data to be sent

Description

Message must have an destination specified explicitly. Used for SOCK_RDM and SOCK_DGRAM messages, and for 'SYN' messages on SOCK_SEQPACKET and SOCK_STREAM connections. (Note: 'SYN+' is prohibited on SOCK_STREAM.)

Return

the number of bytes sent on success, or errno otherwise

int tipc_sendstream(struct socket *sock, struct msghdr *m, size_t dsz)

send stream-oriented data

Parameters

struct socket *sock

socket structure

struct msghdr *m

data to send

size_t dsz

total length of data to be transmitted

Description

Used for SOCK_STREAM data.

Return

the number of bytes sent on success (or partial success), or errno if no data sent

int tipc_send_packet(struct socket *sock, struct msghdr *m, size_t dsz)

send a connection-oriented message

Parameters

struct socket *sock

socket structure

struct msghdr *m

message to send

size_t dsz

length of data to be transmitted

Description

Used for SOCK_SEQPACKET messages.

Return

the number of bytes sent on success, or errno otherwise

void tipc_sk_set_orig_addr(struct msghdr *m, struct sk_buff *skb)

capture sender's address for received message

Parameters

struct msghdr *m

descriptor for message info

struct sk_buff *skb

received message

Note

Address is not captured if not requested by receiver.

int tipc_sk_anc_data_recv(struct msghdr *m, struct sk_buff *skb, struct tipc_sock *tsk)

optionally capture ancillary data for received message

Parameters

struct msghdr *m

descriptor for message info

struct sk_buff *skb

received message buffer

struct tipc_sock *tsk

TIPC port associated with message

Note

Ancillary data is not captured if not requested by receiver.

Return

0 if successful, otherwise errno

int tipc_recvmsg(struct socket *sock, struct msghdr *m, size_t buflen, int flags)

receive packet-oriented message

Parameters

struct socket *sock

network socket

struct msghdr *m

descriptor for message info

size_t buflen

length of user buffer area

int flags

receive flags

Description

Used for SOCK_DGRAM, SOCK_RDM, and SOCK_SEQPACKET messages. If the complete message doesn't fit in user area, truncate it.

Return

size of returned message data, errno otherwise

int tipc_recvstream(struct socket *sock, struct msghdr *m, size_t buflen, int flags)

receive stream-oriented data

Parameters

struct socket *sock

network socket

struct msghdr *m

descriptor for message info

size_t buflen

total size of user buffer area

int flags

receive flags

Description

Used for SOCK_STREAM messages only. If not enough data is available will optionally wait for more; never truncates data.

Return

size of returned message data, errno otherwise

void tipc_write_space(struct sock *sk)

wake up thread if port congestion is released

Parameters

struct sock *sk

socket

void tipc_data_ready(struct sock *sk)

wake up threads to indicate messages have been received

Parameters

struct sock *sk

socket

bool tipc_sk_filter_connect(struct tipc_sock *tsk, struct sk_buff *skb, struct sk_buff_head *xmitq)

check incoming message for a connection-based socket

Parameters

struct tipc_sock *tsk

TIPC socket

struct sk_buff *skb

pointer to message buffer.

struct sk_buff_head *xmitq

for Nagle ACK if any

Return

true if message should be added to receive queue, false otherwise

unsigned int rcvbuf_limit(struct sock *sk, struct sk_buff *skb)

get proper overload limit of socket receive queue

Parameters

struct sock *sk

socket

struct sk_buff *skb

message

Description

For connection oriented messages, irrespective of importance, default queue limit is 2 MB.

For connectionless messages, queue limits are based on message importance as follows:

TIPC_LOW_IMPORTANCE (2 MB) TIPC_MEDIUM_IMPORTANCE (4 MB) TIPC_HIGH_IMPORTANCE (8 MB) TIPC_CRITICAL_IMPORTANCE (16 MB)

Return

overload limit according to corresponding message importance

void tipc_sk_filter_rcv(struct sock *sk, struct sk_buff *skb, struct sk_buff_head *xmitq)

validate incoming message

Parameters

struct sock *sk

socket

struct sk_buff *skb

pointer to message.

struct sk_buff_head *xmitq

output message area (FIXME)

Description

Enqueues message on receive queue if acceptable; optionally handles disconnect indication for a connected socket.

Called with socket lock already taken

int tipc_sk_backlog_rcv(struct sock *sk, struct sk_buff *skb)

handle incoming message from backlog queue

Parameters

struct sock *sk

socket

struct sk_buff *skb

message

Description

Caller must hold socket lock

void tipc_sk_enqueue(struct sk_buff_head *inputq, struct sock *sk, u32 dport, struct sk_buff_head *xmitq)

extract all buffers with destination 'dport' from inputq and try adding them to socket or backlog queue

Parameters

struct sk_buff_head *inputq

list of incoming buffers with potentially different destinations

struct sock *sk

socket where the buffers should be enqueued

u32 dport

port number for the socket

struct sk_buff_head *xmitq

output queue

Description

Caller must hold socket lock

void tipc_sk_rcv(struct net *net, struct sk_buff_head *inputq)

handle a chain of incoming buffers

Parameters

struct net *net

the associated network namespace

struct sk_buff_head *inputq

buffer list containing the buffers Consumes all buffers in list until inputq is empty

Note

may be called in multiple threads referring to the same queue

int tipc_connect(struct socket *sock, struct sockaddr *dest, int destlen, int flags)

establish a connection to another TIPC port

Parameters

struct socket *sock

socket structure

struct sockaddr *dest

socket address for destination port

int destlen

size of socket address data structure

int flags

file-related flags associated with socket

Return

0 on success, errno otherwise

int tipc_listen(struct socket *sock, int len)

allow socket to listen for incoming connections

Parameters

struct socket *sock

socket structure

int len

(unused)

Return

0 on success, errno otherwise

int tipc_accept(struct socket *sock, struct socket *new_sock, int flags, bool kern)

wait for connection request

Parameters

struct socket *sock

listening socket

struct socket *new_sock

new socket that is to be connected

int flags

file-related flags associated with socket

bool kern

caused by kernel or by userspace?

Return

0 on success, errno otherwise

int tipc_shutdown(struct socket *sock, int how)

shutdown socket connection

Parameters

struct socket *sock

socket structure

int how

direction to close (must be SHUT_RDWR)

Description

Terminates connection (if necessary), then purges socket's receive queue.

Return

0 on success, errno otherwise

int tipc_setsockopt(struct socket *sock, int lvl, int opt, sockptr_t ov, unsigned int ol)

set socket option

Parameters

struct socket *sock

socket structure

int lvl

option level

int opt

option identifier

sockptr_t ov

pointer to new option value

unsigned int ol

length of option value

Description

For stream sockets only, accepts and ignores all IPPROTO_TCP options (to ease compatibility).

Return

0 on success, errno otherwise

int tipc_getsockopt(struct socket *sock, int lvl, int opt, char __user *ov, int __user *ol)

get socket option

Parameters

struct socket *sock

socket structure

int lvl

option level

int opt

option identifier

char __user *ov

receptacle for option value

int __user *ol

receptacle for length of option value

Description

For stream sockets only, returns 0 length result for all IPPROTO_TCP options (to ease compatibility).

Return

0 on success, errno otherwise

int tipc_socket_init(void)

initialize TIPC socket interface

Parameters

void

no arguments

Return

0 on success, errno otherwise

void tipc_socket_stop(void)

stop TIPC socket interface

Parameters

void

no arguments

bool tipc_sk_filtering(struct sock *sk)

check if a socket should be traced

Parameters

struct sock *sk

the socket to be examined

Description

sysctl_tipc_sk_filter is used as the socket tuple for filtering: (portid, sock type, name type, name lower, name upper)

Return

true if the socket meets the socket tuple data (value 0 = 'any') or when there is no tuple set (all = 0), otherwise false

bool tipc_sk_overlimit1(struct sock *sk, struct sk_buff *skb)

check if socket rx queue is about to be overloaded, both the rcv and backlog queues are considered

Parameters

struct sock *sk

tipc sk to be checked

struct sk_buff *skb

tipc msg to be checked

Return

true if the socket rx queue allocation is > 90%, otherwise false

bool tipc_sk_overlimit2(struct sock *sk, struct sk_buff *skb)

check if socket rx queue is about to be overloaded, only the rcv queue is considered

Parameters

struct sock *sk

tipc sk to be checked

struct sk_buff *skb

tipc msg to be checked

Return

true if the socket rx queue allocation is > 90%, otherwise false

int tipc_sk_dump(struct sock *sk, u16 dqueues, char *buf)

dump TIPC socket

Parameters

struct sock *sk

tipc sk to be dumped

u16 dqueues

bitmask to decide if any socket queue to be dumped? - TIPC_DUMP_NONE: don't dump socket queues - TIPC_DUMP_SK_SNDQ: dump socket send queue - TIPC_DUMP_SK_RCVQ: dump socket rcv queue - TIPC_DUMP_SK_BKLGQ: dump socket backlog queue - TIPC_DUMP_ALL: dump all the socket queues above

char *buf

returned buffer of dump data in format

TIPC Network Topology Interfaces

bool tipc_sub_check_overlap(struct tipc_service_range *subscribed, struct tipc_service_range *found)

test for subscription overlap with the given values

Parameters

struct tipc_service_range *subscribed

the service range subscribed for

struct tipc_service_range *found

the service range we are checking for match

Description

Returns true if there is overlap, otherwise false.

TIPC Server Interfaces

struct tipc_topsrv

TIPC server structure

Definition:

struct tipc_topsrv {
    struct idr conn_idr;
    spinlock_t idr_lock;
    int idr_in_use;
    struct net *net;
    struct work_struct awork;
    struct workqueue_struct *rcv_wq;
    struct workqueue_struct *send_wq;
    struct socket *listener;
    char name[TIPC_SERVER_NAME_LEN];
};

Members

conn_idr

identifier set of connection

idr_lock

protect the connection identifier set

idr_in_use

amount of allocated identifier entry

net

network namspace instance

awork

accept work item

rcv_wq

receive workqueue

send_wq

send workqueue

listener

topsrv listener socket

name

server name

struct tipc_conn

TIPC connection structure

Definition:

struct tipc_conn {
    struct kref kref;
    int conid;
    struct socket *sock;
    unsigned long flags;
    struct tipc_topsrv *server;
    struct list_head sub_list;
    spinlock_t sub_lock;
    struct work_struct rwork;
    struct list_head outqueue;
    spinlock_t outqueue_lock;
    struct work_struct swork;
};

Members

kref

reference counter to connection object

conid

connection identifier

sock

socket handler associated with connection

flags

indicates connection state

server

pointer to connected server

sub_list

lsit to all pertaing subscriptions

sub_lock

lock protecting the subscription list

rwork

receive work item

outqueue

pointer to first outbound message in queue

outqueue_lock

control access to the outqueue

swork

send work item

TIPC Trace Interfaces

int tipc_skb_dump(struct sk_buff *skb, bool more, char *buf)

dump TIPC skb data

Parameters

struct sk_buff *skb

skb to be dumped

bool more

dump more? - false: dump only tipc msg data - true: dump kernel-related skb data and tipc cb[] array as well

char *buf

returned buffer of dump data in format

int tipc_list_dump(struct sk_buff_head *list, bool more, char *buf)

dump TIPC skb list/queue

Parameters

struct sk_buff_head *list

list of skbs to be dumped

bool more

dump more? - false: dump only the head & tail skbs - true: dump the first & last 5 skbs

char *buf

returned buffer of dump data in format