About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / netlink_mmap.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

1	This file documents how to use memory mapped I/O with netlink.
2	
3	Author: Patrick McHardy <kaber@trash.net>
4	
5	Overview
6	--------
7	
8	Memory mapped netlink I/O can be used to increase throughput and decrease
9	overhead of unicast receive and transmit operations. Some netlink subsystems
10	require high throughput, these are mainly the netfilter subsystems
11	nfnetlink_queue and nfnetlink_log, but it can also help speed up large
12	dump operations of f.i. the routing database.
13	
14	Memory mapped netlink I/O used two circular ring buffers for RX and TX which
15	are mapped into the processes address space.
16	
17	The RX ring is used by the kernel to directly construct netlink messages into
18	user-space memory without copying them as done with regular socket I/O,
19	additionally as long as the ring contains messages no recvmsg() or poll()
20	syscalls have to be issued by user-space to get more message.
21	
22	The TX ring is used to process messages directly from user-space memory, the
23	kernel processes all messages contained in the ring using a single sendmsg()
24	call.
25	
26	Usage overview
27	--------------
28	
29	In order to use memory mapped netlink I/O, user-space needs three main changes:
30	
31	- ring setup
32	- conversion of the RX path to get messages from the ring instead of recvmsg()
33	- conversion of the TX path to construct messages into the ring
34	
35	Ring setup is done using setsockopt() to provide the ring parameters to the
36	kernel, then a call to mmap() to map the ring into the processes address space:
37	
38	- setsockopt(fd, SOL_NETLINK, NETLINK_RX_RING, &params, sizeof(params));
39	- setsockopt(fd, SOL_NETLINK, NETLINK_TX_RING, &params, sizeof(params));
40	- ring = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)
41	
42	Usage of either ring is optional, but even if only the RX ring is used the
43	mapping still needs to be writable in order to update the frame status after
44	processing.
45	
46	Conversion of the reception path involves calling poll() on the file
47	descriptor, once the socket is readable the frames from the ring are
48	processed in order until no more messages are available, as indicated by
49	a status word in the frame header.
50	
51	On kernel side, in order to make use of memory mapped I/O on receive, the
52	originating netlink subsystem needs to support memory mapped I/O, otherwise
53	it will use an allocated socket buffer as usual and the contents will be
54	 copied to the ring on transmission, nullifying most of the performance gains.
55	Dumps of kernel databases automatically support memory mapped I/O.
56	
57	Conversion of the transmit path involves changing message construction to
58	use memory from the TX ring instead of (usually) a buffer declared on the
59	stack and setting up the frame header appropriately. Optionally poll() can
60	be used to wait for free frames in the TX ring.
61	
62	Structured and definitions for using memory mapped I/O are contained in
63	<linux/netlink.h>.
64	
65	RX and TX rings
66	----------------
67	
68	Each ring contains a number of continuous memory blocks, containing frames of
69	fixed size dependent on the parameters used for ring setup.
70	
71	Ring:	[ block 0 ]
72			[ frame 0 ]
73			[ frame 1 ]
74		[ block 1 ]
75			[ frame 2 ]
76			[ frame 3 ]
77		...
78		[ block n ]
79			[ frame 2 * n ]
80			[ frame 2 * n + 1 ]
81	
82	The blocks are only visible to the kernel, from the point of view of user-space
83	the ring just contains the frames in a continuous memory zone.
84	
85	The ring parameters used for setting up the ring are defined as follows:
86	
87	struct nl_mmap_req {
88		unsigned int	nm_block_size;
89		unsigned int	nm_block_nr;
90		unsigned int	nm_frame_size;
91		unsigned int	nm_frame_nr;
92	};
93	
94	Frames are grouped into blocks, where each block is a continuous region of memory
95	and holds nm_block_size / nm_frame_size frames. The total number of frames in
96	the ring is nm_frame_nr. The following invariants hold:
97	
98	- frames_per_block = nm_block_size / nm_frame_size
99	
100	- nm_frame_nr = frames_per_block * nm_block_nr
101	
102	Some parameters are constrained, specifically:
103	
104	- nm_block_size must be a multiple of the architectures memory page size.
105	  The getpagesize() function can be used to get the page size.
106	
107	- nm_frame_size must be equal or larger to NL_MMAP_HDRLEN, IOW a frame must be
108	  able to hold at least the frame header
109	
110	- nm_frame_size must be smaller or equal to nm_block_size
111	
112	- nm_frame_size must be a multiple of NL_MMAP_MSG_ALIGNMENT
113	
114	- nm_frame_nr must equal the actual number of frames as specified above.
115	
116	When the kernel can't allocate physically continuous memory for a ring block,
117	it will fall back to use physically discontinuous memory. This might affect
118	performance negatively, in order to avoid this the nm_frame_size parameter
119	should be chosen to be as small as possible for the required frame size and
120	the number of blocks should be increased instead.
121	
122	Ring frames
123	------------
124	
125	Each frames contain a frame header, consisting of a synchronization word and some
126	meta-data, and the message itself.
127	
128	Frame:	[ header message ]
129	
130	The frame header is defined as follows:
131	
132	struct nl_mmap_hdr {
133		unsigned int	nm_status;
134		unsigned int	nm_len;
135		__u32		nm_group;
136		/* credentials */
137		__u32		nm_pid;
138		__u32		nm_uid;
139		__u32		nm_gid;
140	};
141	
142	- nm_status is used for synchronizing processing between the kernel and user-
143	  space and specifies ownership of the frame as well as the operation to perform
144	
145	- nm_len contains the length of the message contained in the data area
146	
147	- nm_group specified the destination multicast group of message
148	
149	- nm_pid, nm_uid and nm_gid contain the netlink pid, UID and GID of the sending
150	  process. These values correspond to the data available using SOCK_PASSCRED in
151	  the SCM_CREDENTIALS cmsg.
152	
153	The possible values in the status word are:
154	
155	- NL_MMAP_STATUS_UNUSED:
156		RX ring:	frame belongs to the kernel and contains no message
157				for user-space. Approriate action is to invoke poll()
158				to wait for new messages.
159	
160		TX ring:	frame belongs to user-space and can be used for
161				message construction.
162	
163	- NL_MMAP_STATUS_RESERVED:
164		RX ring only:	frame is currently used by the kernel for message
165				construction and contains no valid message yet.
166				Appropriate action is to invoke poll() to wait for
167				new messages.
168	
169	- NL_MMAP_STATUS_VALID:
170		RX ring:	frame contains a valid message. Approriate action is
171				to process the message and release the frame back to
172				the kernel by setting the status to
173				NL_MMAP_STATUS_UNUSED or queue the frame by setting the
174				status to NL_MMAP_STATUS_SKIP.
175	
176		TX ring:	the frame contains a valid message from user-space to
177				be processed by the kernel. After completing processing
178				the kernel will release the frame back to user-space by
179				setting the status to NL_MMAP_STATUS_UNUSED.
180	
181	- NL_MMAP_STATUS_COPY:
182		RX ring only:	a message is ready to be processed but could not be
183				stored in the ring, either because it exceeded the
184				frame size or because the originating subsystem does
185				not support memory mapped I/O. Appropriate action is
186				to invoke recvmsg() to receive the message and release
187				the frame back to the kernel by setting the status to
188				NL_MMAP_STATUS_UNUSED.
189	
190	- NL_MMAP_STATUS_SKIP:
191		RX ring only:	user-space queued the message for later processing, but
192				processed some messages following it in the ring. The
193				kernel should skip this frame when looking for unused
194				frames.
195	
196	The data area of a frame begins at a offset of NL_MMAP_HDRLEN relative to the
197	frame header.
198	
199	TX limitations
200	--------------
201	
202	Kernel processing usually involves validation of the message received by
203	user-space, then processing its contents. The kernel must assure that
204	userspace is not able to modify the message contents after they have been
205	validated. In order to do so, the message is copied from the ring frame
206	to an allocated buffer if either of these conditions is false:
207	
208	- only a single mapping of the ring exists
209	- the file descriptor is not shared between processes
210	
211	This means that for threaded programs, the kernel will fall back to copying.
212	
213	Example
214	-------
215	
216	Ring setup:
217	
218		unsigned int block_size = 16 * getpagesize();
219		struct nl_mmap_req req = {
220			.nm_block_size		= block_size,
221			.nm_block_nr		= 64,
222			.nm_frame_size		= 16384,
223			.nm_frame_nr		= 64 * block_size / 16384,
224		};
225		unsigned int ring_size;
226		void *rx_ring, *tx_ring;
227	
228		/* Configure ring parameters */
229		if (setsockopt(fd, SOL_NETLINK, NETLINK_RX_RING, &req, sizeof(req)) < 0)
230			exit(1);
231		if (setsockopt(fd, SOL_NETLINK, NETLINK_TX_RING, &req, sizeof(req)) < 0)
232			exit(1)
233	
234		/* Calculate size of each individual ring */
235		ring_size = req.nm_block_nr * req.nm_block_size;
236	
237		/* Map RX/TX rings. The TX ring is located after the RX ring */
238		rx_ring = mmap(NULL, 2 * ring_size, PROT_READ | PROT_WRITE,
239			       MAP_SHARED, fd, 0);
240		if ((long)rx_ring == -1L)
241			exit(1);
242		tx_ring = rx_ring + ring_size:
243	
244	Message reception:
245	
246	This example assumes some ring parameters of the ring setup are available.
247	
248		unsigned int frame_offset = 0;
249		struct nl_mmap_hdr *hdr;
250		struct nlmsghdr *nlh;
251		unsigned char buf[16384];
252		ssize_t len;
253	
254		while (1) {
255			struct pollfd pfds[1];
256	
257			pfds[0].fd	= fd;
258			pfds[0].events	= POLLIN | POLLERR;
259			pfds[0].revents	= 0;
260	
261			if (poll(pfds, 1, -1) < 0 && errno != -EINTR)
262				exit(1);
263	
264			/* Check for errors. Error handling omitted */
265			if (pfds[0].revents & POLLERR)
266				<handle error>
267	
268			/* If no new messages, poll again */
269			if (!(pfds[0].revents & POLLIN))
270				continue;
271	
272			/* Process all frames */
273			while (1) {
274				/* Get next frame header */
275				hdr = rx_ring + frame_offset;
276	
277				if (hdr->nm_status == NL_MMAP_STATUS_VALID) {
278					/* Regular memory mapped frame */
279					nlh = (void *)hdr + NL_MMAP_HDRLEN;
280					len = hdr->nm_len;
281	
282					/* Release empty message immediately. May happen
283					 * on error during message construction.
284					 */
285					if (len == 0)
286						goto release;
287				} else if (hdr->nm_status == NL_MMAP_STATUS_COPY) {
288					/* Frame queued to socket receive queue */
289					len = recv(fd, buf, sizeof(buf), MSG_DONTWAIT);
290					if (len <= 0)
291						break;
292					nlh = buf;
293				} else
294					/* No more messages to process, continue polling */
295					break;
296	
297				process_msg(nlh);
298	release:
299				/* Release frame back to the kernel */
300				hdr->nm_status = NL_MMAP_STATUS_UNUSED;
301	
302				/* Advance frame offset to next frame */
303				frame_offset = (frame_offset + frame_size) % ring_size;
304			}
305		}
306	
307	Message transmission:
308	
309	This example assumes some ring parameters of the ring setup are available.
310	A single message is constructed and transmitted, to send multiple messages
311	at once they would be constructed in consecutive frames before a final call
312	to sendto().
313	
314		unsigned int frame_offset = 0;
315		struct nl_mmap_hdr *hdr;
316		struct nlmsghdr *nlh;
317		struct sockaddr_nl addr = {
318			.nl_family	= AF_NETLINK,
319		};
320	
321		hdr = tx_ring + frame_offset;
322		if (hdr->nm_status != NL_MMAP_STATUS_UNUSED)
323			/* No frame available. Use poll() to avoid. */
324			exit(1);
325	
326		nlh = (void *)hdr + NL_MMAP_HDRLEN;
327	
328		/* Build message */
329		build_message(nlh);
330	
331		/* Fill frame header: length and status need to be set */
332		hdr->nm_len	= nlh->nlmsg_len;
333		hdr->nm_status	= NL_MMAP_STATUS_VALID;
334	
335		if (sendto(fd, NULL, 0, 0, &addr, sizeof(addr)) < 0)
336			exit(1);
337	
338		/* Advance frame offset to next frame */
339		frame_offset = (frame_offset + frame_size) % ring_size;
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.