1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2008 Nathan Whitehorn
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 _MACHINE_DBDMA_H_
30#define _MACHINE_DBDMA_H_
31
32#include <sys/param.h>
33#include <machine/bus.h>
34
35/*
36 * Apple's DBDMA (Descriptor-based DMA) interface is a common DMA engine
37 * used by a variety of custom Apple ASICs. It is described in the CHRP
38 * specification and in the book Macintosh Technology in the Common
39 * Hardware Reference Platform, copyright 1995 Apple Computer.
40 */
41
42/* DBDMA Command Values */
43
44enum {
45 DBDMA_OUTPUT_MORE = 0,
46 DBDMA_OUTPUT_LAST = 1,
47 DBDMA_INPUT_MORE = 2,
48 DBDMA_INPUT_LAST = 3,
49
50 DBDMA_STORE_QUAD = 4,
51 DBDMA_LOAD_QUAD = 5,
52 DBDMA_NOP = 6,
53 DBDMA_STOP = 7
54};
55
56/* These codes are for the interrupt, branch, and wait flags */
57
58enum {
59 DBDMA_NEVER = 0,
60 DBDMA_COND_TRUE = 1,
61 DBDMA_COND_FALSE = 2,
62 DBDMA_ALWAYS = 3
63};
64
65/* Channel status bits */
66#define DBDMA_STATUS_RUN (0x01 << 15)
67#define DBDMA_STATUS_PAUSE (0x01 << 14)
68#define DBDMA_STATUS_FLUSH (0x01 << 13)
69#define DBDMA_STATUS_WAKE (0x01 << 12)
70#define DBDMA_STATUS_DEAD (0x01 << 11)
71#define DBDMA_STATUS_ACTIVE (0x01 << 10)
72
73/* Set by hardware if a branch was taken */
74#define DBDMA_STATUS_BRANCH 8
75
76struct dbdma_command;
77typedef struct dbdma_command dbdma_command_t;
78struct dbdma_channel;
79typedef struct dbdma_channel dbdma_channel_t;
80
81int dbdma_allocate_channel(struct resource *dbdma_regs, u_int offset,
82 bus_dma_tag_t parent_dma, int slots, dbdma_channel_t **chan);
83
84int dbdma_resize_channel(dbdma_channel_t *chan, int newslots);
85int dbdma_free_channel(dbdma_channel_t *chan);
86
87void dbdma_run(dbdma_channel_t *chan);
88void dbdma_stop(dbdma_channel_t *chan);
89void dbdma_reset(dbdma_channel_t *chan);
90void dbdma_set_current_cmd(dbdma_channel_t *chan, int slot);
91
92void dbdma_pause(dbdma_channel_t *chan);
93void dbdma_wake(dbdma_channel_t *chan);
94
95/*
96 * DBDMA uses a 16 bit channel control register to describe the current
97 * state of DMA on the channel. The high-order bits (8-15) contain information
98 * on the run state and are listed in the DBDMA_STATUS_* constants above. These
99 * are manipulated with the dbdma_run/stop/reset() routines above.
100 *
101 * The low order bits (0-7) are device dependent status bits. These can be set
102 * and read by both hardware and software. The mask is the set of bits to
103 * modify; if mask is 0x03 and value is 0, the lowest order 2 bits will be
104 * zeroed.
105 */
106
107uint16_t dbdma_get_chan_status(dbdma_channel_t *chan);
108
109uint8_t dbdma_get_device_status(dbdma_channel_t *chan);
110void dbdma_set_device_status(dbdma_channel_t *chan, uint8_t mask,
111 uint8_t value);
112
113/*
114 * Each DBDMA command word has the current channel status register and the
115 * number of residual bytes (requested - actually transferred) written to it
116 * at time of command completion.
117 */
118
119uint16_t dbdma_get_cmd_status(dbdma_channel_t *chan, int slot);
120uint16_t dbdma_get_residuals(dbdma_channel_t *chan, int slot);
121
122void dbdma_clear_cmd_status(dbdma_channel_t *chan, int slot);
123
124/*
125 * The interrupt/branch/wait selector let you specify a set of values
126 * of the device dependent status bits that will cause intterupt/branch/wait
127 * conditions to be taken if the flags for these are set to one of the
128 * DBDMA_COND_* values.
129 *
130 * The condition is considered true if (status & mask) == value.
131 */
132
133void dbdma_set_interrupt_selector(dbdma_channel_t *chan, uint8_t mask,
134 uint8_t value);
135void dbdma_set_branch_selector(dbdma_channel_t *chan, uint8_t mask,
136 uint8_t value);
137void dbdma_set_wait_selector(dbdma_channel_t *chan, uint8_t mask,
138 uint8_t value);
139
140void dbdma_insert_command(dbdma_channel_t *chan, int slot, int command,
141 int stream, bus_addr_t data, size_t count, uint8_t interrupt,
142 uint8_t branch, uint8_t wait, uint32_t branch_slot);
143
144void dbdma_insert_stop(dbdma_channel_t *chan, int slot);
145void dbdma_insert_nop(dbdma_channel_t *chan, int slot);
146void dbdma_insert_branch(dbdma_channel_t *chan, int slot, int to_slot);
147
148void dbdma_sync_commands(dbdma_channel_t *chan, bus_dmasync_op_t op);
149
150void dbdma_save_state(dbdma_channel_t *chan);
151void dbdma_restore_state(dbdma_channel_t *chan);
152
153#endif /* _MACHINE_DBDMA_H_ */