bus_dma.h revision 232356
1116743Ssam/* $NetBSD: bus.h,v 1.12 1997/10/01 08:25:15 fvdl Exp $ */ 2186904Ssam 3116743Ssam/*- 4116743Ssam * Copyright (c) 1996, 1997 The NetBSD Foundation, Inc. 5116743Ssam * All rights reserved. 6116743Ssam * 7116743Ssam * This code is derived from software contributed to The NetBSD Foundation 8116743Ssam * by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 9116743Ssam * NASA Ames Research Center. 10116743Ssam * 11116743Ssam * Redistribution and use in source and binary forms, with or without 12116743Ssam * modification, are permitted provided that the following conditions 13116743Ssam * are met: 14116743Ssam * 1. Redistributions of source code must retain the above copyright 15116743Ssam * notice, this list of conditions and the following disclaimer. 16116743Ssam * 2. Redistributions in binary form must reproduce the above copyright 17116743Ssam * notice, this list of conditions and the following disclaimer in the 18116743Ssam * documentation and/or other materials provided with the distribution. 19116743Ssam * 3. All advertising materials mentioning features or use of this software 20116743Ssam * must display the following acknowledgement: 21116743Ssam * This product includes software developed by the NetBSD 22116743Ssam * Foundation, Inc. and its contributors. 23116743Ssam * 4. Neither the name of The NetBSD Foundation nor the names of its 24116743Ssam * contributors may be used to endorse or promote products derived 25116743Ssam * from this software without specific prior written permission. 26116743Ssam * 27116743Ssam * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 28116743Ssam * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 29116743Ssam * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 30116743Ssam * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 31116743Ssam * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 32116743Ssam * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 33116743Ssam * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 34116743Ssam * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 35116743Ssam * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 36116743Ssam * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 37116743Ssam * POSSIBILITY OF SUCH DAMAGE. 38185522Ssam */ 39185522Ssam 40119783Ssam/*- 41116743Ssam * Copyright (c) 1996 Charles M. Hannum. All rights reserved. 42138570Ssam * Copyright (c) 1996 Christopher G. Demetriou. All rights reserved. 43116743Ssam * 44116743Ssam * Redistribution and use in source and binary forms, with or without 45116743Ssam * modification, are permitted provided that the following conditions 46155481Ssam * are met: 47116743Ssam * 1. Redistributions of source code must retain the above copyright 48155481Ssam * notice, this list of conditions and the following disclaimer. 49155481Ssam * 2. Redistributions in binary form must reproduce the above copyright 50170530Ssam * notice, this list of conditions and the following disclaimer in the 51155481Ssam * documentation and/or other materials provided with the distribution. 52178354Ssam * 3. All advertising materials mentioning features or use of this software 53178354Ssam * must display the following acknowledgement: 54140438Ssam * This product includes software developed by Christopher G. Demetriou 55138570Ssam * for the NetBSD Project. 56155480Ssam * 4. The name of the author may not be used to endorse or promote products 57138570Ssam * derived from this software without specific prior written permission 58116743Ssam * 59147067Ssam * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 60147067Ssam * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 61147067Ssam * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 62147067Ssam * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 63147057Ssam * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 64147057Ssam * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 65147057Ssam * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 66147057Ssam * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 67147057Ssam * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 68147057Ssam * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 69147057Ssam */ 70147057Ssam/* $FreeBSD: head/sys/sys/bus_dma.h 232356 2012-03-01 19:58:34Z jhb $ */ 71147057Ssam 72147057Ssam#ifndef _BUS_DMA_H_ 73147057Ssam#define _BUS_DMA_H_ 74170530Ssam 75170530Ssam#include <sys/_bus_dma.h> 76170530Ssam 77170530Ssam/* 78170530Ssam * Machine independent interface for mapping physical addresses to peripheral 79170530Ssam * bus 'physical' addresses, and assisting with DMA operations. 80170530Ssam * 81170530Ssam * XXX This file is always included from <machine/bus_dma.h> and should not 82138570Ssam * (yet) be included directly. 83116743Ssam */ 84119150Ssam 85178354Ssam/* 86178354Ssam * Flags used in various bus DMA methods. 87170530Ssam */ 88138570Ssam#define BUS_DMA_WAITOK 0x00 /* safe to sleep (pseudo-flag) */ 89116743Ssam#define BUS_DMA_NOWAIT 0x01 /* not safe to sleep */ 90138570Ssam#define BUS_DMA_ALLOCNOW 0x02 /* perform resource allocation now */ 91138570Ssam#define BUS_DMA_COHERENT 0x04 /* hint: map memory in a coherent way */ 92116743Ssam#define BUS_DMA_ZERO 0x08 /* allocate zero'ed memory */ 93138570Ssam#define BUS_DMA_BUS1 0x10 /* placeholders for bus functions... */ 94138570Ssam#define BUS_DMA_BUS2 0x20 95138570Ssam#define BUS_DMA_BUS3 0x40 96138570Ssam#define BUS_DMA_BUS4 0x80 97138570Ssam 98138570Ssam/* 99138570Ssam * The following two flags are non-standard or specific to only certain 100138570Ssam * architectures 101138570Ssam */ 102138570Ssam#define BUS_DMA_NOWRITE 0x100 103184358Ssam#define BUS_DMA_NOCACHE 0x200 104184358Ssam 105184358Ssam/* 106138570Ssam * The following flag is a DMA tag hint that the page offset of the 107116743Ssam * loaded kernel virtual address must be preserved in the first 108138570Ssam * physical segment address, when the KVA is loaded into DMA. 109170530Ssam */ 110170530Ssam#define BUS_DMA_KEEP_PG_OFFSET 0x400 111116743Ssam 112186904Ssam/* Forwards needed by prototypes below. */ 113186904Ssamstruct mbuf; 114116743Ssamstruct uio; 115165185Ssam 116116743Ssam/* 117138570Ssam * Operations performed by bus_dmamap_sync(). 118116743Ssam */ 119116743Ssam#define BUS_DMASYNC_PREREAD 1 120116743Ssam#define BUS_DMASYNC_POSTREAD 2 121140438Ssam#define BUS_DMASYNC_PREWRITE 4 122116743Ssam#define BUS_DMASYNC_POSTWRITE 8 123116743Ssam 124138570Ssam/* 125116743Ssam * bus_dma_segment_t 126186904Ssam * 127186904Ssam * Describes a single contiguous DMA transaction. Values 128138570Ssam * are suitable for programming into DMA registers. 129138570Ssam */ 130138570Ssamtypedef struct bus_dma_segment { 131138570Ssam bus_addr_t ds_addr; /* DMA address */ 132138570Ssam bus_size_t ds_len; /* length of transfer */ 133138570Ssam} bus_dma_segment_t; 134138570Ssam 135158298Ssam/* 136138570Ssam * A function that returns 1 if the address cannot be accessed by 137138570Ssam * a device and 0 if it can be. 138138570Ssam */ 139138570Ssamtypedef int bus_dma_filter_t(void *, bus_addr_t); 140138570Ssam 141138570Ssam/* 142138570Ssam * Generic helper function for manipulating mutexes. 143138570Ssam */ 144138570Ssamvoid busdma_lock_mutex(void *arg, bus_dma_lock_op_t op); 145138570Ssam 146138570Ssam/* 147138570Ssam * Allocate a device specific dma_tag encapsulating the constraints of 148138570Ssam * the parent tag in addition to other restrictions specified: 149138570Ssam * 150138570Ssam * alignment: Alignment for segments. 151138570Ssam * boundary: Boundary that segments cannot cross. 152138570Ssam * lowaddr: Low restricted address that cannot appear in a mapping. 153178354Ssam * highaddr: High restricted address that cannot appear in a mapping. 154186904Ssam * filtfunc: An optional function to further test if an address 155186904Ssam * within the range of lowaddr and highaddr cannot appear 156156073Ssam * in a mapping. 157138570Ssam * filtfuncarg: An argument that will be passed to filtfunc in addition 158138570Ssam * to the address to test. 159138570Ssam * maxsize: Maximum mapping size supported by this tag. 160138570Ssam * nsegments: Number of discontinuities allowed in maps. 161155482Ssam * maxsegsz: Maximum size of a segment in the map. 162170530Ssam * flags: Bus DMA flags. 163170530Ssam * lockfunc: An optional function to handle driver-defined lock 164170530Ssam * operations. 165170530Ssam * lockfuncarg: An argument that will be passed to lockfunc in addition 166170530Ssam * to the lock operation. 167170530Ssam * dmat: A pointer to set to a valid dma tag should the return 168170530Ssam * value of this function indicate success. 169138570Ssam */ 170138570Ssam/* XXX Should probably allow specification of alignment */ 171155482Ssamint bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment, 172155482Ssam bus_addr_t boundary, bus_addr_t lowaddr, 173155482Ssam bus_addr_t highaddr, bus_dma_filter_t *filtfunc, 174167252Ssam void *filtfuncarg, bus_size_t maxsize, int nsegments, 175161425Simp bus_size_t maxsegsz, int flags, bus_dma_lock_t *lockfunc, 176138570Ssam void *lockfuncarg, bus_dma_tag_t *dmat); 177138570Ssam 178138570Ssamint bus_dma_tag_destroy(bus_dma_tag_t dmat); 179138570Ssam 180138570Ssam/* 181138570Ssam * A function that processes a successfully loaded dma map or an error 182138570Ssam * from a delayed load map. 183138570Ssam */ 184170530Ssamtypedef void bus_dmamap_callback_t(void *, bus_dma_segment_t *, int, int); 185138570Ssam 186138570Ssam/* 187138570Ssam * Like bus_dmamap_callback but includes map size in bytes. This is 188138570Ssam * defined as a separate interface to maintain compatibility for users 189138570Ssam * of bus_dmamap_callback_t--at some point these interfaces should be merged. 190178354Ssam */ 191178354Ssamtypedef void bus_dmamap_callback2_t(void *, bus_dma_segment_t *, int, bus_size_t, int); 192178354Ssam 193178354Ssam/* 194138570Ssam * XXX sparc64 uses the same interface, but a much different implementation. 195178354Ssam * <machine/bus_dma.h> for the sparc64 arch contains the equivalent 196178354Ssam * declarations. 197178354Ssam */ 198178354Ssam#if !defined(__sparc64__) 199178354Ssam 200178354Ssam/* 201178354Ssam * Allocate a handle for mapping from kva/uva/physical 202178354Ssam * address space into bus device space. 203178354Ssam */ 204178354Ssamint bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp); 205178354Ssam 206178354Ssam/* 207178354Ssam * Destroy a handle for mapping from kva/uva/physical 208178354Ssam * address space into bus device space. 209178354Ssam */ 210155491Ssamint bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map); 211155486Ssam 212155486Ssam/* 213116743Ssam * Allocate a piece of memory that can be efficiently mapped into 214147256Sbrooks * bus device space based on the constraints listed in the dma tag. 215138570Ssam * A dmamap to for use with dmamap_load is also allocated. 216138570Ssam */ 217178354Ssamint bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags, 218178354Ssam bus_dmamap_t *mapp); 219178354Ssam 220178354Ssam/* 221178354Ssam * Free a piece of memory and its allocated dmamap, that was allocated 222178354Ssam * via bus_dmamem_alloc. 223138570Ssam */ 224116743Ssamvoid bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map); 225159290Ssam 226159290Ssam/* 227116743Ssam * Map the buffer buf into bus space using the dmamap map. 228116743Ssam */ 229155491Ssamint bus_dmamap_load(bus_dma_tag_t dmat, bus_dmamap_t map, void *buf, 230116743Ssam bus_size_t buflen, bus_dmamap_callback_t *callback, 231138570Ssam void *callback_arg, int flags); 232155486Ssam 233138570Ssam/* 234178354Ssam * Like bus_dmamap_load but for mbufs. Note the use of the 235178354Ssam * bus_dmamap_callback2_t interface. 236178354Ssam */ 237178354Ssamint bus_dmamap_load_mbuf(bus_dma_tag_t dmat, bus_dmamap_t map, 238178354Ssam struct mbuf *mbuf, 239178354Ssam bus_dmamap_callback2_t *callback, void *callback_arg, 240178354Ssam int flags); 241178354Ssam 242178354Ssamint bus_dmamap_load_mbuf_sg(bus_dma_tag_t dmat, bus_dmamap_t map, 243178354Ssam struct mbuf *mbuf, bus_dma_segment_t *segs, 244178354Ssam int *nsegs, int flags); 245155496Ssam 246178354Ssam/* 247165571Ssam * Like bus_dmamap_load but for uios. Note the use of the 248170530Ssam * bus_dmamap_callback2_t interface. 249178354Ssam */ 250178354Ssamint bus_dmamap_load_uio(bus_dma_tag_t dmat, bus_dmamap_t map, 251178354Ssam struct uio *ui, 252178354Ssam bus_dmamap_callback2_t *callback, void *callback_arg, 253178354Ssam int flags); 254178354Ssam 255179401Ssam/* 256185744Ssam * Perform a synchronization operation on the given map. 257186904Ssam */ 258189380Ssamvoid _bus_dmamap_sync(bus_dma_tag_t, bus_dmamap_t, bus_dmasync_op_t); 259185744Ssam#define bus_dmamap_sync(dmat, dmamap, op) \ 260178751Ssam do { \ 261178751Ssam if ((dmamap) != NULL) \ 262116743Ssam _bus_dmamap_sync(dmat, dmamap, op); \ 263188783Ssam } while (0) 264116743Ssam 265116743Ssam/* 266155490Ssam * Release the mapping held by map. 267138570Ssam */ 268170530Ssamvoid _bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map); 269187831Ssam#define bus_dmamap_unload(dmat, dmamap) \ 270170530Ssam do { \ 271116743Ssam if ((dmamap) != NULL) \ 272140432Ssam _bus_dmamap_unload(dmat, dmamap); \ 273140432Ssam } while (0) 274140761Ssam 275140761Ssam#endif /* __sparc64__ */ 276140432Ssam 277140432Ssam#endif /* _BUS_DMA_H_ */ 278140432Ssam