1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2012 EMC Corp.
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 *    notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 *    notice, this list of conditions and the following disclaimer in the
14 *    documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 * SUCH DAMAGE.
27 */
28
29#ifndef _SYS_MEMDESC_H_
30#define	_SYS_MEMDESC_H_
31
32struct bio;
33struct bus_dma_segment;
34struct uio;
35struct mbuf;
36struct vm_page;
37union ccb;
38
39/*
40 * struct memdesc encapsulates various memory descriptors and provides
41 * abstract access to them.
42 */
43struct memdesc {
44	union {
45		void			*md_vaddr;
46		vm_paddr_t		md_paddr;
47		struct bus_dma_segment	*md_list;
48		struct uio		*md_uio;
49		struct mbuf		*md_mbuf;
50		struct vm_page 		**md_ma;
51	} u;
52	union {				/* type specific data. */
53		size_t		md_len;	/* VADDR, PADDR, VMPAGES */
54		int		md_nseg; /* VLIST, PLIST */
55	};
56	union {
57		uint32_t	md_offset; /* VMPAGES */
58	};
59	uint32_t	md_type;	/* Type of memory. */
60};
61
62#define	MEMDESC_VADDR	1	/* Contiguous virtual address. */
63#define	MEMDESC_PADDR	2	/* Contiguous physical address. */
64#define	MEMDESC_VLIST	3	/* scatter/gather list of kva addresses. */
65#define	MEMDESC_PLIST	4	/* scatter/gather list of physical addresses. */
66#define	MEMDESC_UIO	6	/* Pointer to a uio (any io). */
67#define	MEMDESC_MBUF	7	/* Pointer to a mbuf (network io). */
68#define	MEMDESC_VMPAGES	8	/* Pointer to array of VM pages. */
69
70static inline struct memdesc
71memdesc_vaddr(void *vaddr, size_t len)
72{
73	struct memdesc mem;
74
75	mem.u.md_vaddr = vaddr;
76	mem.md_len = len;
77	mem.md_type = MEMDESC_VADDR;
78
79	return (mem);
80}
81
82static inline struct memdesc
83memdesc_paddr(vm_paddr_t paddr, size_t len)
84{
85	struct memdesc mem;
86
87	mem.u.md_paddr = paddr;
88	mem.md_len = len;
89	mem.md_type = MEMDESC_PADDR;
90
91	return (mem);
92}
93
94static inline struct memdesc
95memdesc_vlist(struct bus_dma_segment *vlist, int sglist_cnt)
96{
97	struct memdesc mem;
98
99	mem.u.md_list = vlist;
100	mem.md_nseg = sglist_cnt;
101	mem.md_type = MEMDESC_VLIST;
102
103	return (mem);
104}
105
106static inline struct memdesc
107memdesc_plist(struct bus_dma_segment *plist, int sglist_cnt)
108{
109	struct memdesc mem;
110
111	mem.u.md_list = plist;
112	mem.md_nseg = sglist_cnt;
113	mem.md_type = MEMDESC_PLIST;
114
115	return (mem);
116}
117
118static inline struct memdesc
119memdesc_uio(struct uio *uio)
120{
121	struct memdesc mem;
122
123	mem.u.md_uio = uio;
124	mem.md_type = MEMDESC_UIO;
125
126	return (mem);
127}
128
129static inline struct memdesc
130memdesc_mbuf(struct mbuf *mbuf)
131{
132	struct memdesc mem;
133
134	mem.u.md_mbuf = mbuf;
135	mem.md_type = MEMDESC_MBUF;
136
137	return (mem);
138}
139
140static inline struct memdesc
141memdesc_vmpages(struct vm_page **ma, size_t len, u_int ma_offset)
142{
143	struct memdesc mem;
144
145	mem.u.md_ma = ma;
146	mem.md_len = len;
147	mem.md_type = MEMDESC_VMPAGES;
148	mem.md_offset = ma_offset;
149
150	return (mem);
151}
152
153struct memdesc	memdesc_bio(struct bio *bio);
154struct memdesc	memdesc_ccb(union ccb *ccb);
155
156/*
157 * Similar to m_copyback/data, *_copyback copy data from the 'src'
158 * buffer into the memory descriptor's data buffer while *_copydata
159 * copy data from the memory descriptor's data buffer into the the
160 * 'dst' buffer.
161 */
162void	memdesc_copyback(struct memdesc *mem, int off, int size,
163    const void *src);
164void	memdesc_copydata(struct memdesc *mem, int off, int size, void *dst);
165
166/*
167 * This routine constructs a chain of M_EXT mbufs backed by a data
168 * buffer described by a memory descriptor.  Some buffers may require
169 * multiple mbufs.  For memory descriptors using unmapped storage
170 * (e.g. memdesc_vmpages), M_EXTPG mbufs are used.
171 *
172 * Since memory descriptors are not an actual buffer, just a
173 * description of the buffer, the caller is required to supply a
174 * couple of helper routines to manage allocation of the raw mbufs and
175 * associate them with a reference to the underlying buffer.
176 *
177 * The memdesc_alloc_ext_mbuf_t callback is passed the callback
178 * argument as its first argument, the how flag as its second
179 * argument, and the pointer and length of a KVA buffer.  This
180 * callback should allocate an mbuf for the KVA buffer, either by
181 * making a copy of the data or using m_extaddref().
182 *
183 * The memdesc_alloc_extpg_mbuf_t callback is passed the callback
184 * argument as its first argument and the how flag as its second
185 * argument.  It should return an empty mbuf allocated by
186 * mb_alloc_ext_pgs.
187 *
188 * If either of the callbacks returns NULL, any partially allocated
189 * chain is freed and this routine returns NULL.
190 *
191 * If can_truncate is true, then this function might return a short
192 * chain to avoid gratuitously splitting up a page.
193 */
194typedef struct mbuf *memdesc_alloc_ext_mbuf_t(void *, int, void *, size_t);
195typedef struct mbuf *memdesc_alloc_extpg_mbuf_t(void *, int);
196
197struct mbuf *memdesc_alloc_ext_mbufs(struct memdesc *mem,
198    memdesc_alloc_ext_mbuf_t *ext_alloc,
199    memdesc_alloc_extpg_mbuf_t *extpg_alloc, void *cb_arg, int how,
200    size_t offset, size_t len, size_t *actual_len, bool can_truncate);
201
202#endif /* _SYS_MEMDESC_H_ */
203