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_ */