bus_dma.h revision 188350
132517Sgibbs/*	$NetBSD: bus.h,v 1.12 1997/10/01 08:25:15 fvdl Exp $	*/
232517Sgibbs
332517Sgibbs/*-
432517Sgibbs * Copyright (c) 1996, 1997 The NetBSD Foundation, Inc.
532517Sgibbs * All rights reserved.
632517Sgibbs *
732517Sgibbs * This code is derived from software contributed to The NetBSD Foundation
832517Sgibbs * by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
932517Sgibbs * NASA Ames Research Center.
1032517Sgibbs *
1132517Sgibbs * Redistribution and use in source and binary forms, with or without
1232517Sgibbs * modification, are permitted provided that the following conditions
1332517Sgibbs * are met:
1432517Sgibbs * 1. Redistributions of source code must retain the above copyright
1532517Sgibbs *    notice, this list of conditions and the following disclaimer.
1632517Sgibbs * 2. Redistributions in binary form must reproduce the above copyright
1732517Sgibbs *    notice, this list of conditions and the following disclaimer in the
1832517Sgibbs *    documentation and/or other materials provided with the distribution.
1932517Sgibbs * 3. All advertising materials mentioning features or use of this software
2032517Sgibbs *    must display the following acknowledgement:
2132517Sgibbs *	This product includes software developed by the NetBSD
2232517Sgibbs *	Foundation, Inc. and its contributors.
2332517Sgibbs * 4. Neither the name of The NetBSD Foundation nor the names of its
2432517Sgibbs *    contributors may be used to endorse or promote products derived
2532517Sgibbs *    from this software without specific prior written permission.
2632517Sgibbs *
2732517Sgibbs * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
2832517Sgibbs * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
2932517Sgibbs * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
3032517Sgibbs * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
3132517Sgibbs * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
3232517Sgibbs * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
3332517Sgibbs * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
3432517Sgibbs * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
3532517Sgibbs * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
3632517Sgibbs * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
3732517Sgibbs * POSSIBILITY OF SUCH DAMAGE.
3832517Sgibbs */
3932517Sgibbs
40139790Simp/*-
4132517Sgibbs * Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
4232517Sgibbs * Copyright (c) 1996 Christopher G. Demetriou.  All rights reserved.
4332517Sgibbs *
4432517Sgibbs * Redistribution and use in source and binary forms, with or without
4532517Sgibbs * modification, are permitted provided that the following conditions
4632517Sgibbs * are met:
4732517Sgibbs * 1. Redistributions of source code must retain the above copyright
4832517Sgibbs *    notice, this list of conditions and the following disclaimer.
4932517Sgibbs * 2. Redistributions in binary form must reproduce the above copyright
5032517Sgibbs *    notice, this list of conditions and the following disclaimer in the
5132517Sgibbs *    documentation and/or other materials provided with the distribution.
5232517Sgibbs * 3. All advertising materials mentioning features or use of this software
5332517Sgibbs *    must display the following acknowledgement:
5432517Sgibbs *      This product includes software developed by Christopher G. Demetriou
5532517Sgibbs *	for the NetBSD Project.
5632517Sgibbs * 4. The name of the author may not be used to endorse or promote products
5732517Sgibbs *    derived from this software without specific prior written permission
5832517Sgibbs *
5932517Sgibbs * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
6032517Sgibbs * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
6132517Sgibbs * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
6232517Sgibbs * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
6332517Sgibbs * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
6432517Sgibbs * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
6532517Sgibbs * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
6632517Sgibbs * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
6732517Sgibbs * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
6832517Sgibbs * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
6932517Sgibbs */
7050477Speter/* $FreeBSD: head/sys/sys/bus_dma.h 188350 2009-02-08 22:54:58Z imp $ */
7132517Sgibbs
72143598Sscottl#ifndef _BUS_DMA_H_
73143598Sscottl#define _BUS_DMA_H_
7432517Sgibbs
75161927Sjmg#include <sys/_bus_dma.h>
76161927Sjmg
7732517Sgibbs/*
78143598Sscottl * Machine independent interface for mapping physical addresses to peripheral
79143598Sscottl * bus 'physical' addresses, and assisting with DMA operations.
80143598Sscottl *
81143598Sscottl * XXX This file is always included from <machine/bus_dma.h> and should not
82143598Sscottl *     (yet) be included directly.
83143598Sscottl */
84143598Sscottl
85143598Sscottl/*
8632517Sgibbs * Flags used in various bus DMA methods.
8732517Sgibbs */
8832517Sgibbs#define	BUS_DMA_WAITOK		0x00	/* safe to sleep (pseudo-flag) */
8932517Sgibbs#define	BUS_DMA_NOWAIT		0x01	/* not safe to sleep */
9032517Sgibbs#define	BUS_DMA_ALLOCNOW	0x02	/* perform resource allocation now */
91115416Shmp#define	BUS_DMA_COHERENT	0x04	/* hint: map memory in a coherent way */
92118081Smux#define	BUS_DMA_ZERO		0x08	/* allocate zero'ed memory */
9332517Sgibbs#define	BUS_DMA_BUS1		0x10	/* placeholders for bus functions... */
9432517Sgibbs#define	BUS_DMA_BUS2		0x20
9532517Sgibbs#define	BUS_DMA_BUS3		0x40
9632517Sgibbs#define	BUS_DMA_BUS4		0x80
9732517Sgibbs
98143598Sscottl/*
99143598Sscottl * The following two flags are non-standard or specific to only certain
100143598Sscottl * architectures
101143598Sscottl */
102143598Sscottl#define	BUS_DMA_NOWRITE		0x100
103143598Sscottl#define	BUS_DMA_NOCACHE		0x200
104143598Sscottl
105188350Simp/*
106188350Simp * The following flag is a DMA tag hint that the page offset of the
107188350Simp * loaded kernel virtual address must be preserved in the first
108188350Simp * physical segment address, when the KVA is loaded into DMA.
109188350Simp */
110188350Simp#define	BUS_DMA_KEEP_PG_OFFSET	0x400
111188350Simp
11232517Sgibbs/* Forwards needed by prototypes below. */
11332517Sgibbsstruct mbuf;
11432517Sgibbsstruct uio;
11532517Sgibbs
11632517Sgibbs/*
117113347Smux * Operations performed by bus_dmamap_sync().
11832517Sgibbs */
119113347Smux#define	BUS_DMASYNC_PREREAD	1
120113347Smux#define	BUS_DMASYNC_POSTREAD	2
121113347Smux#define	BUS_DMASYNC_PREWRITE	4
122113347Smux#define	BUS_DMASYNC_POSTWRITE	8
12332517Sgibbs
12432517Sgibbs/*
12532517Sgibbs *	bus_dma_segment_t
12632517Sgibbs *
12732517Sgibbs *	Describes a single contiguous DMA transaction.  Values
12832517Sgibbs *	are suitable for programming into DMA registers.
12932517Sgibbs */
13032517Sgibbstypedef struct bus_dma_segment {
13132517Sgibbs	bus_addr_t	ds_addr;	/* DMA address */
13232517Sgibbs	bus_size_t	ds_len;		/* length of transfer */
13332517Sgibbs} bus_dma_segment_t;
13432517Sgibbs
13532517Sgibbs/*
13632517Sgibbs * A function that returns 1 if the address cannot be accessed by
13732517Sgibbs * a device and 0 if it can be.
13832517Sgibbs */
13932517Sgibbstypedef int bus_dma_filter_t(void *, bus_addr_t);
14032517Sgibbs
14132517Sgibbs/*
142143598Sscottl * Generic helper function for manipulating mutexes.
143143598Sscottl */
144143598Sscottlvoid busdma_lock_mutex(void *arg, bus_dma_lock_op_t op);
145143598Sscottl
146143598Sscottl/*
14732517Sgibbs * Allocate a device specific dma_tag encapsulating the constraints of
14832517Sgibbs * the parent tag in addition to other restrictions specified:
14932517Sgibbs *
150122154Sanholt *	alignment:	Alignment for segments.
15132517Sgibbs *	boundary:	Boundary that segments cannot cross.
15232517Sgibbs *	lowaddr:	Low restricted address that cannot appear in a mapping.
15332517Sgibbs *	highaddr:	High restricted address that cannot appear in a mapping.
15432517Sgibbs *	filtfunc:	An optional function to further test if an address
15532517Sgibbs *			within the range of lowaddr and highaddr cannot appear
15632517Sgibbs *			in a mapping.
15732517Sgibbs *	filtfuncarg:	An argument that will be passed to filtfunc in addition
15832517Sgibbs *			to the address to test.
15935767Sgibbs *	maxsize:	Maximum mapping size supported by this tag.
16035767Sgibbs *	nsegments:	Number of discontinuities allowed in maps.
16135767Sgibbs *	maxsegsz:	Maximum size of a segment in the map.
16232517Sgibbs *	flags:		Bus DMA flags.
163122266Sscottl *	lockfunc:	An optional function to handle driver-defined lock
164122266Sscottl *			operations.
165122266Sscottl *	lockfuncarg:	An argument that will be passed to lockfunc in addition
166122266Sscottl *			to the lock operation.
16732517Sgibbs *	dmat:		A pointer to set to a valid dma tag should the return
16832517Sgibbs *			value of this function indicate success.
16932517Sgibbs */
17035767Sgibbs/* XXX Should probably allow specification of alignment */
17178353Salexint bus_dma_tag_create(bus_dma_tag_t parent, bus_size_t alignment,
17235767Sgibbs		       bus_size_t boundary, bus_addr_t lowaddr,
17335767Sgibbs		       bus_addr_t highaddr, bus_dma_filter_t *filtfunc,
17435767Sgibbs		       void *filtfuncarg, bus_size_t maxsize, int nsegments,
175117126Sscottl		       bus_size_t maxsegsz, int flags, bus_dma_lock_t *lockfunc,
176117126Sscottl		       void *lockfuncarg, bus_dma_tag_t *dmat);
17732517Sgibbs
17832517Sgibbsint bus_dma_tag_destroy(bus_dma_tag_t dmat);
17932517Sgibbs
18032517Sgibbs/*
181143598Sscottl * A function that processes a successfully loaded dma map or an error
182143598Sscottl * from a delayed load map.
183143598Sscottl */
184143598Sscottltypedef void bus_dmamap_callback_t(void *, bus_dma_segment_t *, int, int);
185143598Sscottl
186143598Sscottl/*
187143598Sscottl * Like bus_dmamap_callback but includes map size in bytes.  This is
188143598Sscottl * defined as a separate interface to maintain compatibility for users
189143598Sscottl * of bus_dmamap_callback_t--at some point these interfaces should be merged.
190143598Sscottl */
191143598Sscottltypedef void bus_dmamap_callback2_t(void *, bus_dma_segment_t *, int, bus_size_t, int);
192143598Sscottl
193143598Sscottl/*
194143598Sscottl * XXX sparc64 uses the same interface, but a much different implementation.
195143598Sscottl *     <machine/bus_dma.h> for the sparc64 arch contains the equivalent
196143598Sscottl *     declarations.
197143598Sscottl */
198143598Sscottl#if !defined(__sparc64__)
199143598Sscottl
200143598Sscottl/*
20132517Sgibbs * Allocate a handle for mapping from kva/uva/physical
20232517Sgibbs * address space into bus device space.
20332517Sgibbs */
20432517Sgibbsint bus_dmamap_create(bus_dma_tag_t dmat, int flags, bus_dmamap_t *mapp);
20532517Sgibbs
20632517Sgibbs/*
207122154Sanholt * Destroy a handle for mapping from kva/uva/physical
20832517Sgibbs * address space into bus device space.
20932517Sgibbs */
21032517Sgibbsint bus_dmamap_destroy(bus_dma_tag_t dmat, bus_dmamap_t map);
21132517Sgibbs
21232517Sgibbs/*
21335767Sgibbs * Allocate a piece of memory that can be efficiently mapped into
214122154Sanholt * bus device space based on the constraints listed in the dma tag.
21535767Sgibbs * A dmamap to for use with dmamap_load is also allocated.
21635767Sgibbs */
21735767Sgibbsint bus_dmamem_alloc(bus_dma_tag_t dmat, void** vaddr, int flags,
21835767Sgibbs		     bus_dmamap_t *mapp);
21935767Sgibbs
22035767Sgibbs/*
221122154Sanholt * Free a piece of memory and its allocated dmamap, that was allocated
22235767Sgibbs * via bus_dmamem_alloc.
22335767Sgibbs */
22435767Sgibbsvoid bus_dmamem_free(bus_dma_tag_t dmat, void *vaddr, bus_dmamap_t map);
22535767Sgibbs
22635767Sgibbs/*
22732517Sgibbs * Map the buffer buf into bus space using the dmamap map.
22832517Sgibbs */
22932517Sgibbsint bus_dmamap_load(bus_dma_tag_t dmat, bus_dmamap_t map, void *buf,
23032517Sgibbs		    bus_size_t buflen, bus_dmamap_callback_t *callback,
23132517Sgibbs		    void *callback_arg, int flags);
23232517Sgibbs
23332517Sgibbs/*
234104486Ssam * Like bus_dmamap_load but for mbufs.  Note the use of the
235104486Ssam * bus_dmamap_callback2_t interface.
236104486Ssam */
237104486Ssamint bus_dmamap_load_mbuf(bus_dma_tag_t dmat, bus_dmamap_t map,
238104486Ssam			 struct mbuf *mbuf,
239104486Ssam			 bus_dmamap_callback2_t *callback, void *callback_arg,
240104486Ssam			 int flags);
241139840Sscottl
242139840Sscottlint bus_dmamap_load_mbuf_sg(bus_dma_tag_t dmat, bus_dmamap_t map,
243139840Sscottl			    struct mbuf *mbuf, bus_dma_segment_t *segs,
244139840Sscottl			    int *nsegs, int flags);
245139840Sscottl
246104486Ssam/*
247104486Ssam * Like bus_dmamap_load but for uios.  Note the use of the
248104486Ssam * bus_dmamap_callback2_t interface.
249104486Ssam */
250104486Ssamint bus_dmamap_load_uio(bus_dma_tag_t dmat, bus_dmamap_t map,
251104486Ssam			struct uio *ui,
252104486Ssam			bus_dmamap_callback2_t *callback, void *callback_arg,
253104486Ssam			int flags);
254104486Ssam
255104486Ssam/*
256122154Sanholt * Perform a synchronization operation on the given map.
25732517Sgibbs */
258115343Sscottlvoid _bus_dmamap_sync(bus_dma_tag_t, bus_dmamap_t, bus_dmasync_op_t);
259143655Sjmg#define bus_dmamap_sync(dmat, dmamap, op) 			\
260143655Sjmg	do {							\
261143655Sjmg		if ((dmamap) != NULL)				\
262143655Sjmg			_bus_dmamap_sync(dmat, dmamap, op);	\
263143655Sjmg	} while (0)
26432517Sgibbs
26532517Sgibbs/*
26632517Sgibbs * Release the mapping held by map.
26732517Sgibbs */
26832517Sgibbsvoid _bus_dmamap_unload(bus_dma_tag_t dmat, bus_dmamap_t map);
269143655Sjmg#define bus_dmamap_unload(dmat, dmamap) 			\
270143655Sjmg	do {							\
271143655Sjmg		if ((dmamap) != NULL)				\
272143655Sjmg			_bus_dmamap_unload(dmat, dmamap);	\
273143655Sjmg	} while (0)
274143655Sjmg
275143598Sscottl#endif /* __sparc64__ */
27632517Sgibbs
277143598Sscottl#endif /* _BUS_DMA_H_ */
278