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