^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Kernel Connector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Kernel connector - new netlink based userspace <-> kernel space easy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) to use communication module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The Connector driver makes it easy to connect various agents using a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) netlink based network. One must register a callback and an identifier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) When the driver receives a special netlink message with the appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) identifier, the appropriate callback will be called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) From the userspace point of view it's quite straightforward:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) - socket();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) - bind();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) - send();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) - recv();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) But if kernelspace wants to use the full power of such connections, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) driver writer must create special sockets, must know about struct sk_buff
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) handling, etc... The Connector driver allows any kernelspace agents to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) netlink based networking for inter-process communication in a significantly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) easier way::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) struct cb_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) __u32 idx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) __u32 val;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) idx and val are unique identifiers which must be registered in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) connector.h header for in-kernel usage. `void (*callback) (void *)` is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) callback function which will be called when a message with above idx.val
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) is received by the connector core. The argument for that function must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) be dereferenced to `struct cn_msg *`::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) struct cn_msg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) struct cb_id id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) __u32 seq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) __u32 ack;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) __u16 len; /* Length of the following data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) __u16 flags;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) __u8 data[0];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Connector interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) .. kernel-doc:: include/linux/connector.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) When registering new callback user, connector core assigns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) netlink group to the user which is equal to its id.idx.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Protocol description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) The current framework offers a transport layer with fixed headers. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) recommended protocol which uses such a header is as following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) msg->seq and msg->ack are used to determine message genealogy. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) someone sends a message, they use a locally unique sequence and random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) acknowledge number. The sequence number may be copied into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) nlmsghdr->nlmsg_seq too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The sequence number is incremented with each message sent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) If you expect a reply to the message, then the sequence number in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) received message MUST be the same as in the original message, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) acknowledge number MUST be the same + 1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) If we receive a message and its sequence number is not equal to one we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) are expecting, then it is a new message. If we receive a message and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) its sequence number is the same as one we are expecting, but its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) acknowledge is not equal to the sequence number in the original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) message + 1, then it is a new message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Obviously, the protocol header contains the above id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) The connector allows event notification in the following form: kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) driver or userspace process can ask connector to notify it when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) selected ids will be turned on or off (registered or unregistered its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) callback). It is done by sending a special command to the connector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) driver (it also registers itself with id={-1, -1}).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) As example of this usage can be found in the cn_test.c module which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) uses the connector to request notification and to send messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Reliability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Netlink itself is not a reliable protocol. That means that messages can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) be lost due to memory pressure or process' receiving queue overflowed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) so caller is warned that it must be prepared. That is why the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) cn_msg [main connector's message header] contains u32 seq and u32 ack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) fields.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Userspace usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 2.6.14 has a new netlink socket implementation, which by default does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) allow people to send data to netlink groups other than 1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) So, if you wish to use a netlink socket (for example using connector)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) with a different group number, the userspace application must subscribe to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) that group first. It can be achieved by the following pseudocode::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) l_local.nl_family = AF_NETLINK;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) l_local.nl_groups = 12345;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) l_local.nl_pid = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) perror("bind");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) close(s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) return -1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) int on = l_local.nl_groups;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) setsockopt(s, 270, 1, &on, sizeof(on));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) option. To drop a multicast subscription, one should call the above socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 2.6.14 netlink code only allows to select a group which is less or equal to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) the maximum group number, which is used at netlink_kernel_create() time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) group number 12345, you must increment CN_NETLINK_USERS to that number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Additional 0xf numbers are allocated to be used by non-in-kernel users.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Due to this limitation, group 0xffffffff does not work now, so one can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) not use add/remove connector's group notifications, but as far as I know,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) only cn_test.c test module used it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Some work in netlink area is still being done, so things can be changed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 2.6.15 timeframe, if it will happen, documentation will be updated for that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Code samples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Sample code for a connector test module and user space can be found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) in samples/connector/. To build this code, enable CONFIG_CONNECTOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) and CONFIG_SAMPLES.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags