xref: /freebsd/sys/kern/subr_sglist.c (revision 273c26a3c3bea87a241d6879abd4f991db180bf0)
1 /*-
2  * Copyright (c) 2008 Yahoo!, Inc.
3  * All rights reserved.
4  * Written by: John Baldwin <jhb@FreeBSD.org>
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  *    notice, this list of conditions and the following disclaimer in the
13  *    documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the author nor the names of any co-contributors
15  *    may be used to endorse or promote products derived from this software
16  *    without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
29  */
30 
31 #include <sys/cdefs.h>
32 __FBSDID("$FreeBSD$");
33 
34 #include <sys/param.h>
35 #include <sys/kernel.h>
36 #include <sys/bio.h>
37 #include <sys/malloc.h>
38 #include <sys/mbuf.h>
39 #include <sys/proc.h>
40 #include <sys/sglist.h>
41 #include <sys/uio.h>
42 
43 #include <vm/vm.h>
44 #include <vm/vm_page.h>
45 #include <vm/pmap.h>
46 #include <vm/vm_map.h>
47 
48 #include <sys/ktr.h>
49 
50 static MALLOC_DEFINE(M_SGLIST, "sglist", "scatter/gather lists");
51 
52 /*
53  * Convenience macros to save the state of an sglist so it can be restored
54  * if an append attempt fails.  Since sglist's only grow we only need to
55  * save the current count of segments and the length of the ending segment.
56  * Earlier segments will not be changed by an append, and the only change
57  * that can occur to the ending segment is that it can be extended.
58  */
59 struct sgsave {
60 	u_short sg_nseg;
61 	size_t ss_len;
62 };
63 
64 #define	SGLIST_SAVE(sg, sgsave) do {					\
65 	(sgsave).sg_nseg = (sg)->sg_nseg;				\
66 	if ((sgsave).sg_nseg > 0)					\
67 		(sgsave).ss_len = (sg)->sg_segs[(sgsave).sg_nseg - 1].ss_len; \
68 	else								\
69 		(sgsave).ss_len = 0;					\
70 } while (0)
71 
72 #define	SGLIST_RESTORE(sg, sgsave) do {					\
73 	(sg)->sg_nseg = (sgsave).sg_nseg;				\
74 	if ((sgsave).sg_nseg > 0)					\
75 		(sg)->sg_segs[(sgsave).sg_nseg - 1].ss_len = (sgsave).ss_len; \
76 } while (0)
77 
78 /*
79  * Append a single (paddr, len) to a sglist.  sg is the list and ss is
80  * the current segment in the list.  If we run out of segments then
81  * EFBIG will be returned.
82  */
83 static __inline int
84 _sglist_append_range(struct sglist *sg, struct sglist_seg **ssp,
85     vm_paddr_t paddr, size_t len)
86 {
87 	struct sglist_seg *ss;
88 
89 	ss = *ssp;
90 	if (ss->ss_paddr + ss->ss_len == paddr)
91 		ss->ss_len += len;
92 	else {
93 		if (sg->sg_nseg == sg->sg_maxseg)
94 			return (EFBIG);
95 		ss++;
96 		ss->ss_paddr = paddr;
97 		ss->ss_len = len;
98 		sg->sg_nseg++;
99 		*ssp = ss;
100 	}
101 	return (0);
102 }
103 
104 /*
105  * Worker routine to append a virtual address range (either kernel or
106  * user) to a scatter/gather list.
107  */
108 static __inline int
109 _sglist_append_buf(struct sglist *sg, void *buf, size_t len, pmap_t pmap,
110     size_t *donep)
111 {
112 	struct sglist_seg *ss;
113 	vm_offset_t vaddr, offset;
114 	vm_paddr_t paddr;
115 	size_t seglen;
116 	int error;
117 
118 	if (donep)
119 		*donep = 0;
120 	if (len == 0)
121 		return (0);
122 
123 	/* Do the first page.  It may have an offset. */
124 	vaddr = (vm_offset_t)buf;
125 	offset = vaddr & PAGE_MASK;
126 	if (pmap != NULL)
127 		paddr = pmap_extract(pmap, vaddr);
128 	else
129 		paddr = pmap_kextract(vaddr);
130 	seglen = MIN(len, PAGE_SIZE - offset);
131 	if (sg->sg_nseg == 0) {
132 		ss = sg->sg_segs;
133 		ss->ss_paddr = paddr;
134 		ss->ss_len = seglen;
135 		sg->sg_nseg = 1;
136 	} else {
137 		ss = &sg->sg_segs[sg->sg_nseg - 1];
138 		error = _sglist_append_range(sg, &ss, paddr, seglen);
139 		if (error)
140 			return (error);
141 	}
142 	vaddr += seglen;
143 	len -= seglen;
144 	if (donep)
145 		*donep += seglen;
146 
147 	while (len > 0) {
148 		seglen = MIN(len, PAGE_SIZE);
149 		if (pmap != NULL)
150 			paddr = pmap_extract(pmap, vaddr);
151 		else
152 			paddr = pmap_kextract(vaddr);
153 		error = _sglist_append_range(sg, &ss, paddr, seglen);
154 		if (error)
155 			return (error);
156 		vaddr += seglen;
157 		len -= seglen;
158 		if (donep)
159 			*donep += seglen;
160 	}
161 
162 	return (0);
163 }
164 
165 /*
166  * Determine the number of scatter/gather list elements needed to
167  * describe a kernel virtual address range.
168  */
169 int
170 sglist_count(void *buf, size_t len)
171 {
172 	vm_offset_t vaddr, vendaddr;
173 	vm_paddr_t lastaddr, paddr;
174 	int nsegs;
175 
176 	if (len == 0)
177 		return (0);
178 
179 	vaddr = trunc_page((vm_offset_t)buf);
180 	vendaddr = (vm_offset_t)buf + len;
181 	nsegs = 1;
182 	lastaddr = pmap_kextract(vaddr);
183 	vaddr += PAGE_SIZE;
184 	while (vaddr < vendaddr) {
185 		paddr = pmap_kextract(vaddr);
186 		if (lastaddr + PAGE_SIZE != paddr)
187 			nsegs++;
188 		lastaddr = paddr;
189 		vaddr += PAGE_SIZE;
190 	}
191 	return (nsegs);
192 }
193 
194 /*
195  * Determine the number of scatter/gather list elements needed to
196  * describe a buffer backed by an array of VM pages.
197  */
198 int
199 sglist_count_vmpages(vm_page_t *m, size_t pgoff, size_t len)
200 {
201 	vm_paddr_t lastaddr, paddr;
202 	int i, nsegs;
203 
204 	if (len == 0)
205 		return (0);
206 
207 	len += pgoff;
208 	nsegs = 1;
209 	lastaddr = VM_PAGE_TO_PHYS(m[0]);
210 	for (i = 1; len > PAGE_SIZE; len -= PAGE_SIZE, i++) {
211 		paddr = VM_PAGE_TO_PHYS(m[i]);
212 		if (lastaddr + PAGE_SIZE != paddr)
213 			nsegs++;
214 		lastaddr = paddr;
215 	}
216 	return (nsegs);
217 }
218 
219 /*
220  * Allocate a scatter/gather list along with 'nsegs' segments.  The
221  * 'mflags' parameters are the same as passed to malloc(9).  The caller
222  * should use sglist_free() to free this list.
223  */
224 struct sglist *
225 sglist_alloc(int nsegs, int mflags)
226 {
227 	struct sglist *sg;
228 
229 	sg = malloc(sizeof(struct sglist) + nsegs * sizeof(struct sglist_seg),
230 	    M_SGLIST, mflags);
231 	if (sg == NULL)
232 		return (NULL);
233 	sglist_init(sg, nsegs, (struct sglist_seg *)(sg + 1));
234 	return (sg);
235 }
236 
237 /*
238  * Free a scatter/gather list allocated via sglist_allc().
239  */
240 void
241 sglist_free(struct sglist *sg)
242 {
243 
244 	if (sg == NULL)
245 		return;
246 
247 	if (refcount_release(&sg->sg_refs))
248 		free(sg, M_SGLIST);
249 }
250 
251 /*
252  * Append the segments to describe a single kernel virtual address
253  * range to a scatter/gather list.  If there are insufficient
254  * segments, then this fails with EFBIG.
255  */
256 int
257 sglist_append(struct sglist *sg, void *buf, size_t len)
258 {
259 	struct sgsave save;
260 	int error;
261 
262 	if (sg->sg_maxseg == 0)
263 		return (EINVAL);
264 	SGLIST_SAVE(sg, save);
265 	error = _sglist_append_buf(sg, buf, len, NULL, NULL);
266 	if (error)
267 		SGLIST_RESTORE(sg, save);
268 	return (error);
269 }
270 
271 /*
272  * Append the segments to describe a bio's data to a scatter/gather list.
273  * If there are insufficient segments, then this fails with EFBIG.
274  *
275  * NOTE: This function expects bio_bcount to be initialized.
276  */
277 int
278 sglist_append_bio(struct sglist *sg, struct bio *bp)
279 {
280 	int error;
281 
282 	if ((bp->bio_flags & BIO_UNMAPPED) == 0)
283 		error = sglist_append(sg, bp->bio_data, bp->bio_bcount);
284 	else
285 		error = sglist_append_vmpages(sg, bp->bio_ma,
286 		    bp->bio_ma_offset, bp->bio_bcount);
287 	return (error);
288 }
289 
290 /*
291  * Append a single physical address range to a scatter/gather list.
292  * If there are insufficient segments, then this fails with EFBIG.
293  */
294 int
295 sglist_append_phys(struct sglist *sg, vm_paddr_t paddr, size_t len)
296 {
297 	struct sglist_seg *ss;
298 	struct sgsave save;
299 	int error;
300 
301 	if (sg->sg_maxseg == 0)
302 		return (EINVAL);
303 	if (len == 0)
304 		return (0);
305 
306 	if (sg->sg_nseg == 0) {
307 		sg->sg_segs[0].ss_paddr = paddr;
308 		sg->sg_segs[0].ss_len = len;
309 		sg->sg_nseg = 1;
310 		return (0);
311 	}
312 	ss = &sg->sg_segs[sg->sg_nseg - 1];
313 	SGLIST_SAVE(sg, save);
314 	error = _sglist_append_range(sg, &ss, paddr, len);
315 	if (error)
316 		SGLIST_RESTORE(sg, save);
317 	return (error);
318 }
319 
320 /*
321  * Append the segments that describe a single mbuf chain to a
322  * scatter/gather list.  If there are insufficient segments, then this
323  * fails with EFBIG.
324  */
325 int
326 sglist_append_mbuf(struct sglist *sg, struct mbuf *m0)
327 {
328 	struct sgsave save;
329 	struct mbuf *m;
330 	int error;
331 
332 	if (sg->sg_maxseg == 0)
333 		return (EINVAL);
334 
335 	error = 0;
336 	SGLIST_SAVE(sg, save);
337 	for (m = m0; m != NULL; m = m->m_next) {
338 		if (m->m_len > 0) {
339 			error = sglist_append(sg, m->m_data, m->m_len);
340 			if (error) {
341 				SGLIST_RESTORE(sg, save);
342 				return (error);
343 			}
344 		}
345 	}
346 	return (0);
347 }
348 
349 /*
350  * Append the segments that describe a buffer spanning an array of VM
351  * pages.  The buffer begins at an offset of 'pgoff' in the first
352  * page.
353  */
354 int
355 sglist_append_vmpages(struct sglist *sg, vm_page_t *m, size_t pgoff,
356     size_t len)
357 {
358 	struct sgsave save;
359 	struct sglist_seg *ss;
360 	vm_paddr_t paddr;
361 	size_t seglen;
362 	int error, i;
363 
364 	if (sg->sg_maxseg == 0)
365 		return (EINVAL);
366 	if (len == 0)
367 		return (0);
368 
369 	SGLIST_SAVE(sg, save);
370 	i = 0;
371 	if (sg->sg_nseg == 0) {
372 		seglen = min(PAGE_SIZE - pgoff, len);
373 		sg->sg_segs[0].ss_paddr = VM_PAGE_TO_PHYS(m[0]) + pgoff;
374 		sg->sg_segs[0].ss_len = seglen;
375 		sg->sg_nseg = 1;
376 		pgoff = 0;
377 		len -= seglen;
378 		i++;
379 	}
380 	ss = &sg->sg_segs[sg->sg_nseg - 1];
381 	for (; len > 0; i++, len -= seglen) {
382 		seglen = min(PAGE_SIZE - pgoff, len);
383 		paddr = VM_PAGE_TO_PHYS(m[i]) + pgoff;
384 		error = _sglist_append_range(sg, &ss, paddr, seglen);
385 		if (error) {
386 			SGLIST_RESTORE(sg, save);
387 			return (error);
388 		}
389 		pgoff = 0;
390 	}
391 	return (0);
392 }
393 
394 /*
395  * Append the segments that describe a single user address range to a
396  * scatter/gather list.  If there are insufficient segments, then this
397  * fails with EFBIG.
398  */
399 int
400 sglist_append_user(struct sglist *sg, void *buf, size_t len, struct thread *td)
401 {
402 	struct sgsave save;
403 	int error;
404 
405 	if (sg->sg_maxseg == 0)
406 		return (EINVAL);
407 	SGLIST_SAVE(sg, save);
408 	error = _sglist_append_buf(sg, buf, len,
409 	    vmspace_pmap(td->td_proc->p_vmspace), NULL);
410 	if (error)
411 		SGLIST_RESTORE(sg, save);
412 	return (error);
413 }
414 
415 /*
416  * Append the segments that describe a single uio to a scatter/gather
417  * list.  If there are insufficient segments, then this fails with
418  * EFBIG.
419  */
420 int
421 sglist_append_uio(struct sglist *sg, struct uio *uio)
422 {
423 	struct iovec *iov;
424 	struct sgsave save;
425 	size_t resid, minlen;
426 	pmap_t pmap;
427 	int error, i;
428 
429 	if (sg->sg_maxseg == 0)
430 		return (EINVAL);
431 
432 	resid = uio->uio_resid;
433 	iov = uio->uio_iov;
434 
435 	if (uio->uio_segflg == UIO_USERSPACE) {
436 		KASSERT(uio->uio_td != NULL,
437 		    ("sglist_append_uio: USERSPACE but no thread"));
438 		pmap = vmspace_pmap(uio->uio_td->td_proc->p_vmspace);
439 	} else
440 		pmap = NULL;
441 
442 	error = 0;
443 	SGLIST_SAVE(sg, save);
444 	for (i = 0; i < uio->uio_iovcnt && resid != 0; i++) {
445 		/*
446 		 * Now at the first iovec to load.  Load each iovec
447 		 * until we have exhausted the residual count.
448 		 */
449 		minlen = MIN(resid, iov[i].iov_len);
450 		if (minlen > 0) {
451 			error = _sglist_append_buf(sg, iov[i].iov_base, minlen,
452 			    pmap, NULL);
453 			if (error) {
454 				SGLIST_RESTORE(sg, save);
455 				return (error);
456 			}
457 			resid -= minlen;
458 		}
459 	}
460 	return (0);
461 }
462 
463 /*
464  * Append the segments that describe at most 'resid' bytes from a
465  * single uio to a scatter/gather list.  If there are insufficient
466  * segments, then only the amount that fits is appended.
467  */
468 int
469 sglist_consume_uio(struct sglist *sg, struct uio *uio, size_t resid)
470 {
471 	struct iovec *iov;
472 	size_t done;
473 	pmap_t pmap;
474 	int error, len;
475 
476 	if (sg->sg_maxseg == 0)
477 		return (EINVAL);
478 
479 	if (uio->uio_segflg == UIO_USERSPACE) {
480 		KASSERT(uio->uio_td != NULL,
481 		    ("sglist_consume_uio: USERSPACE but no thread"));
482 		pmap = vmspace_pmap(uio->uio_td->td_proc->p_vmspace);
483 	} else
484 		pmap = NULL;
485 
486 	error = 0;
487 	while (resid > 0 && uio->uio_resid) {
488 		iov = uio->uio_iov;
489 		len = iov->iov_len;
490 		if (len == 0) {
491 			uio->uio_iov++;
492 			uio->uio_iovcnt--;
493 			continue;
494 		}
495 		if (len > resid)
496 			len = resid;
497 
498 		/*
499 		 * Try to append this iovec.  If we run out of room,
500 		 * then break out of the loop.
501 		 */
502 		error = _sglist_append_buf(sg, iov->iov_base, len, pmap, &done);
503 		iov->iov_base = (char *)iov->iov_base + done;
504 		iov->iov_len -= done;
505 		uio->uio_resid -= done;
506 		uio->uio_offset += done;
507 		resid -= done;
508 		if (error)
509 			break;
510 	}
511 	return (0);
512 }
513 
514 /*
515  * Allocate and populate a scatter/gather list to describe a single
516  * kernel virtual address range.
517  */
518 struct sglist *
519 sglist_build(void *buf, size_t len, int mflags)
520 {
521 	struct sglist *sg;
522 	int nsegs;
523 
524 	if (len == 0)
525 		return (NULL);
526 
527 	nsegs = sglist_count(buf, len);
528 	sg = sglist_alloc(nsegs, mflags);
529 	if (sg == NULL)
530 		return (NULL);
531 	if (sglist_append(sg, buf, len) != 0) {
532 		sglist_free(sg);
533 		return (NULL);
534 	}
535 	return (sg);
536 }
537 
538 /*
539  * Clone a new copy of a scatter/gather list.
540  */
541 struct sglist *
542 sglist_clone(struct sglist *sg, int mflags)
543 {
544 	struct sglist *new;
545 
546 	if (sg == NULL)
547 		return (NULL);
548 	new = sglist_alloc(sg->sg_maxseg, mflags);
549 	if (new == NULL)
550 		return (NULL);
551 	new->sg_nseg = sg->sg_nseg;
552 	bcopy(sg->sg_segs, new->sg_segs, sizeof(struct sglist_seg) *
553 	    sg->sg_nseg);
554 	return (new);
555 }
556 
557 /*
558  * Calculate the total length of the segments described in a
559  * scatter/gather list.
560  */
561 size_t
562 sglist_length(struct sglist *sg)
563 {
564 	size_t space;
565 	int i;
566 
567 	space = 0;
568 	for (i = 0; i < sg->sg_nseg; i++)
569 		space += sg->sg_segs[i].ss_len;
570 	return (space);
571 }
572 
573 /*
574  * Split a scatter/gather list into two lists.  The scatter/gather
575  * entries for the first 'length' bytes of the 'original' list are
576  * stored in the '*head' list and are removed from 'original'.
577  *
578  * If '*head' is NULL, then a new list will be allocated using
579  * 'mflags'.  If M_NOWAIT is specified and the allocation fails,
580  * ENOMEM will be returned.
581  *
582  * If '*head' is not NULL, it should point to an empty sglist.  If it
583  * does not have enough room for the remaining space, then EFBIG will
584  * be returned.  If '*head' is not empty, then EINVAL will be
585  * returned.
586  *
587  * If 'original' is shared (refcount > 1), then EDOOFUS will be
588  * returned.
589  */
590 int
591 sglist_split(struct sglist *original, struct sglist **head, size_t length,
592     int mflags)
593 {
594 	struct sglist *sg;
595 	size_t space, split;
596 	int count, i;
597 
598 	if (original->sg_refs > 1)
599 		return (EDOOFUS);
600 
601 	/* Figure out how big of a sglist '*head' has to hold. */
602 	count = 0;
603 	space = 0;
604 	split = 0;
605 	for (i = 0; i < original->sg_nseg; i++) {
606 		space += original->sg_segs[i].ss_len;
607 		count++;
608 		if (space >= length) {
609 			/*
610 			 * If 'length' falls in the middle of a
611 			 * scatter/gather list entry, then 'split'
612 			 * holds how much of that entry will remain in
613 			 * 'original'.
614 			 */
615 			split = space - length;
616 			break;
617 		}
618 	}
619 
620 	/* Nothing to do, so leave head empty. */
621 	if (count == 0)
622 		return (0);
623 
624 	if (*head == NULL) {
625 		sg = sglist_alloc(count, mflags);
626 		if (sg == NULL)
627 			return (ENOMEM);
628 		*head = sg;
629 	} else {
630 		sg = *head;
631 		if (sg->sg_maxseg < count)
632 			return (EFBIG);
633 		if (sg->sg_nseg != 0)
634 			return (EINVAL);
635 	}
636 
637 	/* Copy 'count' entries to 'sg' from 'original'. */
638 	bcopy(original->sg_segs, sg->sg_segs, count *
639 	    sizeof(struct sglist_seg));
640 	sg->sg_nseg = count;
641 
642 	/*
643 	 * If we had to split a list entry, fixup the last entry in
644 	 * 'sg' and the new first entry in 'original'.  We also
645 	 * decrement 'count' by 1 since we will only be removing
646 	 * 'count - 1' segments from 'original' now.
647 	 */
648 	if (split != 0) {
649 		count--;
650 		sg->sg_segs[count].ss_len -= split;
651 		original->sg_segs[count].ss_paddr =
652 		    sg->sg_segs[count].ss_paddr + split;
653 		original->sg_segs[count].ss_len = split;
654 	}
655 
656 	/* Trim 'count' entries from the front of 'original'. */
657 	original->sg_nseg -= count;
658 	bcopy(original->sg_segs + count, original->sg_segs, count *
659 	    sizeof(struct sglist_seg));
660 	return (0);
661 }
662 
663 /*
664  * Append the scatter/gather list elements in 'second' to the
665  * scatter/gather list 'first'.  If there is not enough space in
666  * 'first', EFBIG is returned.
667  */
668 int
669 sglist_join(struct sglist *first, struct sglist *second)
670 {
671 	struct sglist_seg *flast, *sfirst;
672 	int append;
673 
674 	/* If 'second' is empty, there is nothing to do. */
675 	if (second->sg_nseg == 0)
676 		return (0);
677 
678 	/*
679 	 * If the first entry in 'second' can be appended to the last entry
680 	 * in 'first' then set append to '1'.
681 	 */
682 	append = 0;
683 	flast = &first->sg_segs[first->sg_nseg - 1];
684 	sfirst = &second->sg_segs[0];
685 	if (first->sg_nseg != 0 &&
686 	    flast->ss_paddr + flast->ss_len == sfirst->ss_paddr)
687 		append = 1;
688 
689 	/* Make sure 'first' has enough room. */
690 	if (first->sg_nseg + second->sg_nseg - append > first->sg_maxseg)
691 		return (EFBIG);
692 
693 	/* Merge last in 'first' and first in 'second' if needed. */
694 	if (append)
695 		flast->ss_len += sfirst->ss_len;
696 
697 	/* Append new segments from 'second' to 'first'. */
698 	bcopy(first->sg_segs + first->sg_nseg, second->sg_segs + append,
699 	    (second->sg_nseg - append) * sizeof(struct sglist_seg));
700 	first->sg_nseg += second->sg_nseg - append;
701 	sglist_reset(second);
702 	return (0);
703 }
704 
705 /*
706  * Generate a new scatter/gather list from a range of an existing
707  * scatter/gather list.  The 'offset' and 'length' parameters specify
708  * the logical range of the 'original' list to extract.  If that range
709  * is not a subset of the length of 'original', then EINVAL is
710  * returned.  The new scatter/gather list is stored in '*slice'.
711  *
712  * If '*slice' is NULL, then a new list will be allocated using
713  * 'mflags'.  If M_NOWAIT is specified and the allocation fails,
714  * ENOMEM will be returned.
715  *
716  * If '*slice' is not NULL, it should point to an empty sglist.  If it
717  * does not have enough room for the remaining space, then EFBIG will
718  * be returned.  If '*slice' is not empty, then EINVAL will be
719  * returned.
720  */
721 int
722 sglist_slice(struct sglist *original, struct sglist **slice, size_t offset,
723     size_t length, int mflags)
724 {
725 	struct sglist *sg;
726 	size_t space, end, foffs, loffs;
727 	int count, i, fseg;
728 
729 	/* Nothing to do. */
730 	if (length == 0)
731 		return (0);
732 
733 	/* Figure out how many segments '*slice' needs to have. */
734 	end = offset + length;
735 	space = 0;
736 	count = 0;
737 	fseg = 0;
738 	foffs = loffs = 0;
739 	for (i = 0; i < original->sg_nseg; i++) {
740 		space += original->sg_segs[i].ss_len;
741 		if (space > offset) {
742 			/*
743 			 * When we hit the first segment, store its index
744 			 * in 'fseg' and the offset into the first segment
745 			 * of 'offset' in 'foffs'.
746 			 */
747 			if (count == 0) {
748 				fseg = i;
749 				foffs = offset - (space -
750 				    original->sg_segs[i].ss_len);
751 				CTR1(KTR_DEV, "sglist_slice: foffs = %08lx",
752 				    foffs);
753 			}
754 			count++;
755 
756 			/*
757 			 * When we hit the last segment, break out of
758 			 * the loop.  Store the amount of extra space
759 			 * at the end of this segment in 'loffs'.
760 			 */
761 			if (space >= end) {
762 				loffs = space - end;
763 				CTR1(KTR_DEV, "sglist_slice: loffs = %08lx",
764 				    loffs);
765 				break;
766 			}
767 		}
768 	}
769 
770 	/* If we never hit 'end', then 'length' ran off the end, so fail. */
771 	if (space < end)
772 		return (EINVAL);
773 
774 	if (*slice == NULL) {
775 		sg = sglist_alloc(count, mflags);
776 		if (sg == NULL)
777 			return (ENOMEM);
778 		*slice = sg;
779 	} else {
780 		sg = *slice;
781 		if (sg->sg_maxseg < count)
782 			return (EFBIG);
783 		if (sg->sg_nseg != 0)
784 			return (EINVAL);
785 	}
786 
787 	/*
788 	 * Copy over 'count' segments from 'original' starting at
789 	 * 'fseg' to 'sg'.
790 	 */
791 	bcopy(original->sg_segs + fseg, sg->sg_segs,
792 	    count * sizeof(struct sglist_seg));
793 	sg->sg_nseg = count;
794 
795 	/* Fixup first and last segments if needed. */
796 	if (foffs != 0) {
797 		sg->sg_segs[0].ss_paddr += foffs;
798 		sg->sg_segs[0].ss_len -= foffs;
799 		CTR2(KTR_DEV, "sglist_slice seg[0]: %08lx:%08lx",
800 		    (long)sg->sg_segs[0].ss_paddr, sg->sg_segs[0].ss_len);
801 	}
802 	if (loffs != 0) {
803 		sg->sg_segs[count - 1].ss_len -= loffs;
804 		CTR2(KTR_DEV, "sglist_slice seg[%d]: len %08x", count - 1,
805 		    sg->sg_segs[count - 1].ss_len);
806 	}
807 	return (0);
808 }
809