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