summaryrefslogtreecommitdiff
path: root/share/man/man9/bus_dma.9
blob: 1747c3daec6887e50065ad6bfbcddb8262ee8df4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
.\"	$OpenBSD: bus_dma.9,v 1.18 2003/06/06 20:56:32 jmc Exp $
.\" $NetBSD: bus_dma.9,v 1.14 2000/06/14 06:49:19 cgd Exp $
.\"
.\" Copyright (c) 1996, 1997, 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
.\" NASA Ames Research Center.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgment:
.\" 	This product includes software developed by the NetBSD
.\" 	Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 23, 2000
.Dt BUS_DMA 9
.Os
.Sh NAME
.Nm bus_dma
.Nd bus and machine independent DMA mapping interface
.Sh SYNOPSIS
.Fd #include <machine/bus.h>
.Sh DESCRIPTION
The
.Nm
interface provides a bus and machine independent mechanism
for managing DMA data transfers to and from devices.
.Pp
The basic abstraction is the bus_dmamap_t, a pointer to a structure
which contains an array of bus_dma_segment_t's (dm_segs) and a count
of how many are currently valid (dm_nsegs).
.Pp
Each segment in the array describes a single physical area of memory
which can be DMA'd, with a starting address (ds_addr) and a length
(ds_len).
These are the values that must be communicated to the DMA device.
Taken together the segments exactly and completely describe the buffer
being used to transfer data.
.Pp
bus_dma_tag_t's are an opaque type, received from higher software
layers and are never created, changed, deleted or even examined in
this interface.
.Pp
The basic cycle to transfer data to/from a DMA device is:
.Bd -literal
bus_dmamap_create();         /* get a dmamap to load/unload          */

for each DMA xfer {
        bus_dmamem_alloc();  /* allocate some DMA'able memory        */
        bus_dmamem_map();    /* map it into the kernel address space */

        /*
         * Fill the allocated DMA'able memory with whatever data
         * is to be sent out, using the pointer obtained with
         * bus_dmamem_map().
         */

        bus_dmamap_load();   /* initialize the segments of dmamap    */
        bus_dmamap_sync();   /* synchronize/flush any DMA cache      */

        for (i=0; i<dm_nsegs; i++) {
                /*
                 * Tell the DMA device the physical address
                 * (dmamap->dm_segs[i].ds_addr) and the length
                 * (dmamap->dm_segs[i].ds_len) of the memory to xfer.
                 *
                 * Start the DMA, wait until it's done
                 */
        }

        bus_dmamap_sync();   /* synchronize/flush any DMA cache      */
        bus_dmamap_unload(); /* prepare dmamap for reuse             */

        /*
         * Copy any data desired from the DMA'able memory using the
         * pointer created by bus_dmamem_map().
         */

        bus_dmamem_unmap();  /* free kernel virtual address space    */
        bus_dmamem_free();   /* free DMA'able memory                 */
}

bus_dmamap_destroy();        /* release any resources used by dmamap */
.Ed
.Sh DATA TYPES
Individual implementations may name these structures whatever they wish,
providing that the external representations are:
.Bl -tag -width "bus_dma_segment_t"
.It Fa bus_addr_t
A device bus address to be used for CPU access or DMA.
.It Fa bus_size_t
The size of a bus address range.
.It Fa bus_dma_tag_t
A machine-dependent opaque type describing the implementation of DMA for
a given host/bus.
Machine-dependent code is responsible for passing these structures to a
bus's autoconfiguration machinery, which in turn passes it down to the device
drivers.
.It Fa bus_dma_segment_t
A structure describing an individual DMA segment.
The structure may have machine-dependent members and arbitrary layout, but
has at least the following members:
.Bd -literal
	bus_addr_t	ds_addr;
	bus_size_t	ds_len;
.Ed
.Pp
The values in
.Fa ds_addr
and
.Fa ds_len
are suitable for programming into a DMA controller's address and length
registers.
.It Fa bus_dmamap_t
A pointer to a structure describing an individual DMA mapping.
The structure may have machine-dependent members and arbitrary layout, but
has at least the following members:
.Bd -literal
	int		   dm_nsegs;
	bus_dma_segment_t *dm_segs;
.Ed
.Pp
The
.Fa dm_segs
member may be an array of segments or a pointer to an array of segments.
The
.Fa dm_nsegs
member indicates the number of segments in
.Fa dm_segs .
.El
.Sh DMA MAPS
.nr nS 1
.Ft int
.Fn bus_dmamap_create "bus_dma_tag_t tag" "bus_size_t size" "int nsegments" \
                      "bus_size_t maxsegsz" "bus_size_t boundary" "int flags" \
                      "bus_dmamap_t *dmamp"
.Ft void
.Fn bus_dmamap_destroy "bus_dma_tag_t tag" "bus_dmamap_t dmam"
.nr nS 0
.Pp
The
.Fn bus_dmamap_create
function allocates a DMA handle and initializes it according to the parameters
provided.
This function returns 0 on success, an error code otherwise.
.Pp
The
.Fn bus_dmamap_create
arguments are as follows:
.Bl -tag -width nsegments -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa size
This is the maximum DMA transfer that can be mapped by the handle.
.It Fa nsegments
Number of segments the device can support in a single DMA transaction.
This may be the number of scatter-gather descriptors supported by the
device.
.It Fa maxsegsz
The maximum number of bytes that may be transferred by any given DMA
segment.
.It Fa boundary
Some DMA controllers are not able to transfer data that crosses a
particular boundary.
This argument allows this boundary to be specified.
The boundary lines begin at 0, and occur every
.Fa boundary
bytes.
Mappings may begin on a boundary line but may not end on or cross a
boundary line.
If no boundary condition needs to be observed, a
.Fa boundary
argument of 0 should be used.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_ALLOCNOW -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_ALLOCNOW
Perform any resource allocation this handle may need now.
If this is not specified, the allocation may be deferred to
.Fn bus_dmamap_load .
If this flag is specified,
.Fn bus_dmamap_load
will not block on resource allocation.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.El
.It Fa dmamp
This is a pointer to a bus_dmamap_t.
A DMA map will be allocated and pointed to by
.Fa dmamp
upon successful completion of this routine.
.El
.Pp
The
.Fn bus_dmamap_destroy
function frees all resources associated with a given DMA handle.
This function always succeeds if given valid arguments.
.Pp
The
.Fn bus_dmamap_destroy
arguments are as follows:
.Bl -tag -width dmam -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa dmam
The DMA handle to destroy.
.El
.Pp
In the event that the DMA handle contains a valid mapping, the mapping
will be unloaded via the same mechanism used by
.Fn bus_dmamap_unload .
.Sh DMA MAP SEGMENTS
.nr nS 1
.Ft int
.Fn bus_dmamap_load "bus_dma_tag_t tag" "bus_dmamap_t dmam" "void *buf" \
                    "bus_size_t buflen" "struct proc *p" "int flags"
.Ft int
.Fn bus_dmamap_load_mbuf "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
                         "struct mbuf *chain" "int flags"
.Ft int
.Fn bus_dmamap_load_uio "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
                        "struct uio *uio" "int flags"
.Ft int
.Fn bus_dmamap_load_raw "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
                        "bus_dma_segment_t *segs" "int nsegs" \
                        "bus_size_t size" "int flags"
.Ft void
.Fn bus_dmamap_unload "bus_dma_tag_t tag" "bus_dmamap_t dmam"
.nr nS 0
.Pp
The
.Fn bus_dmamap_load
function loads a DMA handle with mappings for a DMA transfer.
It assumes that all pages involved in a DMA transfer are wired.
This function returns 0 on success, an error code otherwise.
.Pp
The
.Fn bus_dmamap_load
arguments are as follows:
.Bl -tag -width buflen -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa dmam
The DMA handle with which to map the transfer.
.It Fa buf
The buffer to be used for the DMA transfer.
.It Fa buflen
The size of the buffer.
.It Fa p
Used to indicate the address space in which the buffer is located.
If
.Dv NULL ,
the buffer is assumed to be in kernel space.
Otherwise, the buffer is assumed to be in process
.Fa p Ns 's
address space.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_STREAMING -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.It Dv BUS_DMA_STREAMING
By default, the
.Nm
API assumes that there is coherency between memory and the device
performing the DMA transaction.
Some platforms, however, have special hardware, such as an
.Dq I/O cache ,
which may improve performance
of some types of DMA transactions, but which break the assumption
that there is coherency between memory and the device performing
the DMA transaction.
This flag allows the use of this special hardware, provided that
the device is doing sequential, unidirectional transfers which
conform to certain alignment and size constraints defined by the
platform.
If the platform does not support the feature, or if
the buffer being loaded into the DMA map does not conform to the
constraints required for use of the feature, then this flag will
be silently ignored.
Also refer to the use of this flag with the
.Fn bus_dmamem_alloc
function.
.It Dv BUS_DMA_READ
This is a hint to the machine-dependent back-end that indicates the
mapping will be used only for a
.Em "device -\*[Gt] memory"
transaction.
The back-end may perform optimizations based on this information.
.It Dv BUS_DMA_WRITE
This is a hint to the machine-dependent back-end that indicates the
mapping will be used only for a
.Em "memory -\*[Gt] device"
transaction.
The back-end may perform optimizations based on this information.
.El
.El
.Pp
As noted above, if a DMA handle is created with
.Dv BUS_DMA_ALLOCNOW ,
.Fn bus_dmamap_load
will never block.
.Pp
If a call to
.Fn bus_dmamap_load
fails, the mapping in the DMA handle will be invalid.
It is the responsibility of the caller to clean up any inconsistent
device state resulting from incomplete iteration through the uio.
.Pp
The
.Fn bus_dmamap_load_mbuf
function is a variation of
.Fn bus_dmamap_load
which maps mbuf chains for DMA transfers.
Mbuf chains are assumed to be in kernel virtual address space.
.Pp
The
.Fn bus_dmamap_load_uio
function is a variation of
.Fn bus_dmamap_load
which maps buffers pointed to by
.Fa uio
for DMA transfers.
The value of
.Fa "uio->uio_segflg"
will determine if the buffers are in user or kernel virtual address
space.
If the buffers are in user address space, the buffers are assumed to be
in
.Fa "uio->uio_procp" Ns 's
address space.
.Pp
The
.Fn bus_dmamap_load_raw
function is a variation of
.Fn bus_dmamap_load
which maps buffers allocated by
.Fn bus_dmamem_alloc
(see below).
The
.Fa segs
argument is an array of bus_dma_segment_t's filled in by
.Fn bus_dmamem_alloc .
The
.Fa nsegs
argument is the number of segments in the array.
The
.Fa size
argument is the size of the DMA transfer.
.Pp
The
.Fn bus_dmamap_unload
function deletes the mappings for a given DMA handle.
This function always succeeds if given valid arguments.
.Pp
The
.Fn bus_dmamap_unload
arguments are as follows:
.Bl -tag -width dmam -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa dmam
The DMA handle containing the mappings which are to be deleted.
.El
.Pp
If the DMA handle was created with
.Dv BUS_DMA_ALLOCNOW ,
.Fn bus_dmamap_unload
will not free the corresponding resources which were allocated by
.Fn bus_dmamap_create .
This is to ensure that
.Fn bus_dmamap_load
will never block on resources if the handle was created with
.Dv BUS_DMA_ALLOCNOW .
.Sh SYNCHRONIZATION
.nr nS 1
.Ft void
.Fn bus_dmamap_sync "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
                    "bus_dmasync_op_t ops"
.nr nS 0
.Pp
The
.Fn bus_dmamap_sync
function performs pre- and post-DMA operation cache and/or buffer
synchronization.
This function always succeeds if given valid arguments.
.Pp
The
.Fn bus_dmamap_sync
arguments are as follows:
.Bl -tag -width "dmam" -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa dmam
The DMA mapping to be synchronized.
.It Fa ops
One or more synchronization operations to perform.
The following DMA synchronization operations are defined:
.Bl -tag -width BUS_DMASYNC_POSTWRITE -compact
.It Dv BUS_DMASYNC_PREREAD
Perform any pre-read DMA cache and/or bounce operations.
.It Dv BUS_DMASYNC_POSTREAD
Perform any post-read DMA cache and/or bounce operations.
.It Dv BUS_DMASYNC_PREWRITE
Perform any pre-write DMA cache and/or bounce operations.
.It Dv BUS_DMASYNC_POSTWRITE
Perform any post-write DMA cache and/or bounce operations.
.El
.Pp
More than one operation may performed in a given synchronization call.
Mixing of
.Em PRE
and
.Em POST
operations is not allowed, and behavior is undefined if this is attempted.
.El
.Pp
Synchronization operations are expressed from the perspective of the
host RAM, e.g., a
.Em "device -> memory"
operation is a
.Em READ
and a
.Em "memory -> device"
operation is a
.Em WRITE .
.Pp
.Fn bus_dmamap_sync
may consult state kept within the DMA map to determine if the memory is
mapped in a DMA coherent fashion.
If so,
.Fn bus_dmamap_sync
may elect to skip certain expensive operations, such as flushing of the
data cache.
See
.Fn bus_dmamem_map
for more information on this subject.
.Pp
On platforms which implement reordered stores,
.Fn bus_dmamap_sync
will always cause the store buffer to be flushed.
.Pp
This function exists so that multiple read and write transfers can be
performed with the same buffer, and so that drivers can explicitly
inform the
.Nm
code when their data is
.Dq ready
in its DMA buffer.
.Pp
An example of multiple read-write use of a single mapping
might look like:
.Bd -literal
bus_dmamap_load(...);

while (not done) {
	/* invalidate soon-to-be-stale cache blocks */
	bus_dmamap_sync(..., BUS_DMASYNC_PREREAD);

	[ do read DMA ]

	/* copy from bounce */
	bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD);

	/* read data now in driver-provided buffer */

	[ computation ]

	/* data to be written now in driver-provided buffer */

	/* flush write buffers and writeback, copy to bounce */
	bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE);

	[ do write DMA ]

	/* probably a no-op, but provided for consistency */
	bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE);
}

bus_dmamap_unload(...);
.Ed
.Pp
If DMA read and write operations are not preceded and followed by the
appropriate synchronization operations, behavior is undefined.
.Sh DMA-SAFE MEMORY
.nr nS 1
.Ft int
.Fn bus_dmamem_alloc "bus_dma_tag_t tag" "bus_size_t size" \
                     "bus_size_t alignment" "bus_size_t boundary" \
                     "bus_dma_segment_t *segs" "int nsegs" "int *rsegs" \
                     "int flags"
.Ft void
.Fn bus_dmamem_free "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs"
.nr nS 0
.Pp
The
.Fn bus_dmamem_alloc
function allocates memory that is "DMA safe" for the bus corresponding to the
given tag.
This function returns 0 on success, or an error code indicating mode of
failure.
.Pp
The mapping of this memory is machine-dependent (or "opaque");
machine-independent code should not assume that the addresses returned
are valid in kernel virtual address space, or that the addresses
returned are system physical addresses.
The address value returned as part of
.Fa segs
can thus not be used to program DMA controller address registers.
Only the values in the
.Fa dm_segs
array of a successfully loaded DMA map (using
.Fn bus_dmamap_load )
can be used for this purpose.
.Pp
Allocations will always be rounded to the hardware page size.
Callers may wish to take advantage of this, and cluster allocation of
small data structures.
.Pp
The
.Fn bus_dmamem_alloc
arguments are as follows:
.Bl -tag -width alignment -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa size
The amount of memory to allocate.
.It Fa alignment
Each segment in the allocated memory will be aligned to this value.
If the alignment is less than a hardware page size, it will be rounded
up to the hardware page size.
This value must be a power of two.
.It Fa boundary
Each segment in the allocated memory must not cross this boundary
(relative to zero).
This value must be a power of two.
A boundary value less than the size of the allocation is invalid.
.It Fa segs
An array of bus_dma_segment_t's, filled in as memory is allocated,
representing the opaque addresses of the memory chunks.
.It Fa nsegs
Specifies the number of segments in
.Fa segs ,
and this is the maximum number of segments that the allocated memory may
contain.
.It Fa rsegs
Used to return the actual number of segments the memory contains.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_STREAMING -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_STREAMING
Adjusts, if necessary, the size, alignment, and boundary constraints
to conform to the platform-dependent requirements for the use of the
.Dv BUS_DMA_STREAMING
flag with the
.Fn bus_dmamap_load
function.
If the platform does not support the
.Dv BUS_DMA_STREAMING
feature, or if the size, alignment, and boundary constraints
would already satisfy the platform's requirements, this flag
is silently ignored.
The
.Dv BUS_DMA_STREAMING
flag will never relax the constraints specified in the call.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.El
.El
.Pp
All pages allocated by
.Fn bus_dmamem_alloc
will be wired down until they are freed by
.Fn bus_dmamem_free .
.Pp
The
.Fn bus_dmamem_free
function frees memory previously allocated by
.Fn bus_dmamem_alloc ,
invalidating any mapping.
This function always succeeds if given valid arguments.
.Pp
The
.Fn bus_dmamem_free
arguments are as follows:
.Bl -tag -width nsegs -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa segs
The array of bus_dma_segment_t's filled in by
.Fn bus_dmamem_alloc .
.It Fa nsegs
The number of segments in
.Fa segs .
.El
.Sh MAPPING DMA-SAFE MEMORY
.nr nS 1
.Ft int
.Fn bus_dmamem_map "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" \
                   "size_t size" "caddr_t *kvap" "int flags"
.Ft void
.Fn bus_dmamem_unmap "bus_dma_tag_t tag" "caddr_t kva" "size_t size"
.Ft paddr_t
.Fn bus_dmamem_mmap "bus_dma_tag_t tag" "bus_dma_segment_t *segs" \
                    "int nsegs" "off_t off" "int prot" "int flags"
.nr nS 0
.Pp
The
.Fn bus_dmamem_map
function maps memory allocated with
.Fn bus_dmamem_alloc
into kernel virtual address space.
This function returns 0 on success, an error code otherwise, and must not be
called from an interrupt context.
.Pp
The
.Fn bus_dmamem_map
arguments are as follows:
.Bl -tag -width flags -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa segs
The array of bus_dma_segment_t's filled in by
.Fn bus_dmamem_alloc ,
representing the memory regions to map.
.It Fa nsegs
The number of segments in
.Fa segs .
.It Fa size
The size of the mapping.
.It Fa kvap
Filled in to specify the kernel virtual address where the memory is
mapped.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_COHERENT -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.It Dv BUS_DMA_COHERENT
This flag is a
.Em hint
to machine-dependent code.
If possible, map the memory in such a way as it will be DMA coherent.
This may include mapping the pages into uncached address space or
setting the cache-inhibit bits in page table entries.
If implementation of DMA coherent mappings is impossible, this is
ignored.
.Pp
Later, when this memory is loaded into a DMA map, machine-dependent code
will take whatever steps are necessary to determine if the memory was
mapped in a DMA coherent fashion.
This may include checking if the kernel virtual address lies within
uncached address space or if the cache-inhibit bits are set in page
table entries.
If it is determined that the mapping is DMA coherent, state may be
placed into the DMA map for use by later calls to
.Fn bus_dmamap_sync .
.El
.El
.Pp
The
.Fn bus_dmamem_unmap
function unmaps memory previously mapped with
.Fn bus_dmamem_map ,
freeing the kernel virtual address space used by the mapping.
This function always succeeds if given valid arguments, but must not be
called from an interrupt context.
.Pp
.Fn bus_dmamem_unmap
arguments are as follows:
.Bl -tag -width size -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa kva
The kernel virtual address of the mapped memory.
.It Fa size
The size of the mapping.
.El
.Pp
The
.Fn bus_dmamem_mmap
function provides support for user
.Xr mmap 2 Ns 'ing
of DMA-safe memory.
.Fn bus_dmamem_mmap
is to be called by a device driver's (*d_mmap)() entry
point, which is called by the device pager for each page to be mapped.
This function returns an opaque value to be interpreted by the device
pager, or -1 on failure.
.Fn bus_dmamem_mmap
arguments are
as follows:
.Bl -tag -width nsegs -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
.Fa <bus>_attach_args .
.It Fa segs
The array of bus_dma_segment_t's filled in by
.Fn bus_dmamem_alloc ,
representing the memory to be
.Xr mmap 2 Ns 'ed .
.It Fa nsegs
The number of elements in the
.Fa segs
array.
.It Fa off
The offset of the page in DMA memory which is to be mapped.
.It Fa prot
The protection codes for the mapping.
.It Fa flags
Flags are defined as follows:
.Bl -tag -width BUS_DMA_COHERENT -compact
.It Dv BUS_DMA_WAITOK
It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.It Dv BUS_DMA_COHERENT
See
.Fn bus_dmamem_map
above for a description of this flag.
.El
.El
.Sh SEE ALSO
.Xr bus_space 9
.Sh HISTORY
The
.Nm
interface appeared in
.Nx 1.3 .
.Sh AUTHORS
The
.Nm
interface was designed and implemented by Jason R. Thorpe of the
Numerical Aerospace Simulation Facility, NASA Ames Research Center.
Additional input on the
.Nm
design was provided by Chris Demetriou, Charles Hannum, Ross Harvey,
Matthew Jacob, Jonathan Stone, and Matt Thomas.