summaryrefslogtreecommitdiff
path: root/arch/arm/plat-mxc/include/mach/dmaengine.h
diff options
context:
space:
mode:
Diffstat (limited to 'arch/arm/plat-mxc/include/mach/dmaengine.h')
-rw-r--r--arch/arm/plat-mxc/include/mach/dmaengine.h493
1 files changed, 493 insertions, 0 deletions
diff --git a/arch/arm/plat-mxc/include/mach/dmaengine.h b/arch/arm/plat-mxc/include/mach/dmaengine.h
new file mode 100644
index 000000000000..1b28fb3b881f
--- /dev/null
+++ b/arch/arm/plat-mxc/include/mach/dmaengine.h
@@ -0,0 +1,493 @@
+/*
+ * Copyright (C) 2010 Freescale Semiconductor, Inc. All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef __ASM_ARM_ARCH_DMA_H
+#define __ASM_ARM_ARCH_DMA_H
+
+#ifndef ARCH_DMA_PIO_WORDS
+#define DMA_PIO_WORDS 15
+#else
+#define DMA_PIO_WORDS ARCH_DMA_PIO_WORDS
+#endif
+
+#define MXS_DMA_ALIGNMENT 8
+
+/**
+ * struct mxs_dma_cmd_bits - MXS DMA hardware command bits.
+ *
+ * This structure describes the in-memory layout of the command bits in a DMA
+ * command. See the appropriate reference manual for a detailed description
+ * of what these bits mean to the DMA hardware.
+ */
+struct mxs_dma_cmd_bits {
+ unsigned int command:2;
+#define NO_DMA_XFER 0x00
+#define DMA_WRITE 0x01
+#define DMA_READ 0x02
+#define DMA_SENSE 0x03
+
+ unsigned int chain:1;
+ unsigned int irq:1;
+ unsigned int nand_lock:1;
+ unsigned int nand_wait_4_ready:1;
+ unsigned int dec_sem:1;
+ unsigned int wait4end:1;
+ unsigned int halt_on_terminate:1;
+ unsigned int terminate_flush:1;
+ unsigned int resv2:2;
+ unsigned int pio_words:4;
+ unsigned int bytes:16;
+};
+
+/**
+ * struct mxs_dma_cmd - MXS DMA hardware command.
+ *
+ * This structure describes the in-memory layout of an entire DMA command,
+ * including space for the maximum number of PIO accesses. See the appropriate
+ * reference manual for a detailed description of what these fields mean to the
+ * DMA hardware.
+ */
+struct mxs_dma_cmd {
+ unsigned long next;
+ union {
+ unsigned long data;
+ struct mxs_dma_cmd_bits bits;
+ } cmd;
+ union {
+ dma_addr_t address;
+ unsigned long alternate;
+ };
+ unsigned long pio_words[DMA_PIO_WORDS];
+};
+
+/**
+ * struct mxs_dma_desc - MXS DMA command descriptor.
+ *
+ * This structure incorporates an MXS DMA hardware command structure, along
+ * with metadata.
+ *
+ * @cmd: The MXS DMA hardware command block.
+ * @flags: Flags that represent the state of this DMA descriptor.
+ * @address: The physical address of this descriptor.
+ * @buffer: A convenient place for software to put the virtual address of the
+ * associated data buffer (the physical address of the buffer
+ * appears in the DMA command). The MXS platform DMA software doesn't
+ * use this field -- it is provided as a convenience.
+ * @node: Links this structure into a list.
+ */
+struct mxs_dma_desc {
+ struct mxs_dma_cmd cmd;
+ unsigned int flags;
+#define MXS_DMA_DESC_READY 0x80000000
+#define MXS_DMA_DESC_FIRST 0x00000001
+#define MXS_DMA_DESC_LAST 0x00000002
+ dma_addr_t address;
+ void *buffer;
+ struct list_head node;
+};
+
+struct mxs_dma_info {
+ unsigned int status;
+#define MXS_DMA_INFO_ERR 0x00000001
+#define MXS_DMA_INFO_ERR_STAT 0x00010000
+ unsigned int buf_addr;
+};
+
+/**
+ * struct mxs_dma_chan - MXS DMA channel
+ *
+ * This structure represents a single DMA channel. The MXS platform code
+ * maintains an array of these structures to represent every DMA channel in the
+ * system (see mxs_dma_channels).
+ *
+ * @name: A human-readable string that describes how this channel is
+ * being used or what software "owns" it. This field is set when
+ * when the channel is reserved by mxs_dma_request().
+ * @dev: A pointer to a struct device *, cast to an unsigned long, and
+ * representing the software that "owns" the channel. This field
+ * is set when when the channel is reserved by mxs_dma_request().
+ * @lock: Arbitrates access to this channel.
+ * @dma: A pointer to a struct mxs_dma_device representing the driver
+ * code that operates this channel.
+ * @flags: Flag bits that represent the state of this channel.
+ * @active_num: If the channel is not busy, this value is zero. If the channel
+ * is busy, this field contains the number of DMA command
+ * descriptors at the head of the active list that the hardware
+ * has been told to process. This value is set at the moment the
+ * channel is enabled by mxs_dma_enable(). More descriptors may
+ * arrive after the channel is enabled, so the number of
+ * descriptors on the active list may be greater than this value.
+ * In fact, it should always be active_num + pending_num.
+ * @pending_num: The number of DMA command descriptors at the tail of the
+ * active list that the hardware has not been told to process.
+ * @active: The list of DMA command descriptors either currently being
+ * processed by the hardware or waiting to be processed.
+ * Descriptors being processed appear at the head of the list,
+ * while pending descriptors appear at the tail. The total number
+ * should always be active_num + pending_num.
+ * @done: The list of DMA command descriptors that have either been
+ * processed by the DMA hardware or aborted by a call to
+ * mxs_dma_disable().
+ */
+struct mxs_dma_chan {
+ const char *name;
+ unsigned long dev;
+ spinlock_t lock;
+ struct mxs_dma_device *dma;
+ unsigned int flags;
+#define MXS_DMA_FLAGS_IDLE 0x00000000
+#define MXS_DMA_FLAGS_BUSY 0x00000001
+#define MXS_DMA_FLAGS_FREE 0x00000000
+#define MXS_DMA_FLAGS_ALLOCATED 0x00010000
+#define MXS_DMA_FLAGS_VALID 0x80000000
+ unsigned int active_num;
+ unsigned int pending_num;
+ struct list_head active;
+ struct list_head done;
+};
+
+/**
+ * struct mxs_dma_device - DMA channel driver interface.
+ *
+ * This structure represents the driver that operates a DMA channel. Every
+ * struct mxs_dma_chan contains a pointer to a structure of this type, which is
+ * installed when the driver registers to "own" the channel (see
+ * mxs_dma_device_register()).
+ */
+struct mxs_dma_device {
+ struct list_head node;
+ const char *name;
+ void __iomem *base;
+ unsigned int chan_base;
+ unsigned int chan_num;
+ unsigned int data;
+ struct platform_device *pdev;
+
+ /* operations */
+ int (*enable) (struct mxs_dma_chan *, unsigned int);
+ void (*disable) (struct mxs_dma_chan *, unsigned int);
+ void (*reset) (struct mxs_dma_device *, unsigned int);
+ void (*freeze) (struct mxs_dma_device *, unsigned int);
+ void (*unfreeze) (struct mxs_dma_device *, unsigned int);
+ int (*read_semaphore) (struct mxs_dma_device *, unsigned int);
+ void (*add_semaphore) (struct mxs_dma_device *, unsigned int, unsigned);
+ void (*info)(struct mxs_dma_device *,
+ unsigned int, struct mxs_dma_info *info);
+ void (*enable_irq) (struct mxs_dma_device *, unsigned int, int);
+ int (*irq_is_pending) (struct mxs_dma_device *, unsigned int);
+ void (*ack_irq) (struct mxs_dma_device *, unsigned int);
+
+ void (*set_target) (struct mxs_dma_device *, unsigned int, int);
+};
+
+/**
+ * mxs_dma_device_register - Register a DMA driver.
+ *
+ * This function registers a driver for a contiguous group of DMA channels (the
+ * ordering of DMA channels is specified by the globally unique DMA channel
+ * numbers given in mach/dma.h).
+ *
+ * @pdev: A pointer to a structure that represents the driver. This structure
+ * contains fields that specify the first DMA channel number and the
+ * number of channels.
+ */
+extern int mxs_dma_device_register(struct mxs_dma_device *pdev);
+
+/**
+ * mxs_dma_request - Request to reserve a DMA channel.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @dev: A pointer to a struct device representing the channel "owner."
+ * @name: A human-readable string that identifies the channel owner or the
+ * purpose of the channel.
+ */
+extern int mxs_dma_request(int channel, struct device *dev, const char *name);
+
+/**
+ * mxs_dma_release - Release a DMA channel.
+ *
+ * This function releases a DMA channel from its current owner.
+ *
+ * The channel will NOT be released if it's marked "busy" (see
+ * mxs_dma_enable()).
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @dev: A pointer to a struct device representing the channel "owner." If
+ * this doesn't match the owner given to mxs_dma_request(), the
+ * channel will NOT be released.
+ */
+extern void mxs_dma_release(int channel, struct device *dev);
+
+/**
+ * mxs_dma_enable - Enable a DMA channel.
+ *
+ * If the given channel has any DMA descriptors on its active list, this
+ * function causes the DMA hardware to begin processing them.
+ *
+ * This function marks the DMA channel as "busy," whether or not there are any
+ * descriptors to process.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern int mxs_dma_enable(int channel);
+
+/**
+ * mxs_dma_disable - Disable a DMA channel.
+ *
+ * This function shuts down a DMA channel and marks it as "not busy." Any
+ * descriptors on the active list are immediately moved to the head of the
+ * "done" list, whether or not they have actually been processed by the
+ * hardware. The "ready" flags of these descriptors are NOT cleared, so they
+ * still appear to be active.
+ *
+ * This function immediately shuts down a DMA channel's hardware, aborting any
+ * I/O that may be in progress, potentially leaving I/O hardware in an undefined
+ * state. It is unwise to call this function if there is ANY chance the hardware
+ * is still processing a command.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern void mxs_dma_disable(int channel);
+
+/**
+ * mxs_dma_reset - Resets the DMA channel hardware.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern void mxs_dma_reset(int channel);
+
+/**
+ * mxs_dma_freeze - Freeze a DMA channel.
+ *
+ * This function causes the channel to continuously fail arbitration for bus
+ * access, which halts all forward progress without losing any state. A call to
+ * mxs_dma_unfreeze() will cause the channel to continue its current operation
+ * with no ill effect.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern void mxs_dma_freeze(int channel);
+
+/**
+ * mxs_dma_unfreeze - Unfreeze a DMA channel.
+ *
+ * This function reverses the effect of mxs_dma_freeze(), enabling the DMA
+ * channel to continue from where it was frozen.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+
+extern void mxs_dma_unfreeze(int channel);
+
+/* get dma channel information */
+extern int mxs_dma_get_info(int channel, struct mxs_dma_info *info);
+
+/**
+ * mxs_dma_cooked - Clean up processed DMA descriptors.
+ *
+ * This function removes processed DMA descriptors from the "active" list. Pass
+ * in a non-NULL list head to get the descriptors moved to your list. Pass NULL
+ * to get the descriptors moved to the channel's "done" list. Descriptors on
+ * the "done" list can be retrieved with mxs_dma_get_cooked().
+ *
+ * This function marks the DMA channel as "not busy" if no unprocessed
+ * descriptors remain on the "active" list.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @head: If this is not NULL, it is the list to which the processed
+ * descriptors should be moved. If this list is NULL, the descriptors
+ * will be moved to the "done" list.
+ */
+extern int mxs_dma_cooked(int channel, struct list_head *head);
+
+/**
+ * mxs_dma_read_semaphore - Read a DMA channel's hardware semaphore.
+ *
+ * As used by the MXS platform's DMA software, the DMA channel's hardware
+ * semaphore reflects the number of DMA commands the hardware will process, but
+ * has not yet finished. This is a volatile value read directly from hardware,
+ * so it must be be viewed as immediately stale.
+ *
+ * If the channel is not marked busy, or has finished processing all its
+ * commands, this value should be zero.
+ *
+ * See mxs_dma_append() for details on how DMA command blocks must be configured
+ * to maintain the expected behavior of the semaphore's value.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern int mxs_dma_read_semaphore(int channel);
+
+/**
+ * mxs_dma_irq_is_pending - Check if a DMA interrupt is pending.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern int mxs_dma_irq_is_pending(int channel);
+
+/**
+ * mxs_dma_enable_irq - Enable or disable DMA interrupt.
+ *
+ * This function enables the given DMA channel to interrupt the CPU.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @en: True if the interrupt for this channel should be enabled. False
+ * otherwise.
+ */
+extern void mxs_dma_enable_irq(int channel, int en);
+
+/**
+ * mxs_dma_ack_irq - Clear DMA interrupt.
+ *
+ * The software that is using the DMA channel must register to receive its
+ * interrupts and, when they arrive, must call this function to clear them.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ */
+extern void mxs_dma_ack_irq(int channel);
+
+/**
+ * mxs_dma_set_target - Set the target for a DMA channel.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @target: Indicates the target for the channel.
+ */
+extern void mxs_dma_set_target(int channel, int target);
+
+/* mxs dma utility functions */
+extern struct mxs_dma_desc *mxs_dma_alloc_desc(void);
+extern void mxs_dma_free_desc(struct mxs_dma_desc *);
+
+/**
+ * mxs_dma_cmd_address - Return the address of the command within a descriptor.
+ *
+ * @desc: The DMA descriptor of interest.
+ */
+static inline unsigned int mxs_dma_cmd_address(struct mxs_dma_desc *desc)
+{
+ return desc->address += offsetof(struct mxs_dma_desc, cmd);
+}
+
+/**
+ * mxs_dma_desc_pending - Check if descriptor is on a channel's active list.
+ *
+ * This function returns the state of a descriptor's "ready" flag. This flag is
+ * usually set only if the descriptor appears on a channel's active list. The
+ * descriptor may or may not have already been processed by the hardware.
+ *
+ * The "ready" flag is set when the descriptor is submitted to a channel by a
+ * call to mxs_dma_append() or mxs_dma_append_list(). The "ready" flag is
+ * cleared when a processed descriptor is moved off the active list by a call
+ * to mxs_dma_cooked(). The "ready" flag is NOT cleared if the descriptor is
+ * aborted by a call to mxs_dma_disable().
+ *
+ * @desc: The DMA descriptor of interest.
+ */
+static inline int mxs_dma_desc_pending(struct mxs_dma_desc *pdesc)
+{
+ return pdesc->flags & MXS_DMA_DESC_READY;
+}
+
+/**
+ * mxs_dma_desc_append - Add a DMA descriptor to a channel.
+ *
+ * If the descriptor list for this channel is not empty, this function sets the
+ * CHAIN bit and the NEXTCMD_ADDR fields in the last descriptor's DMA command so
+ * it will chain to the new descriptor's command.
+ *
+ * Then, this function marks the new descriptor as "ready," adds it to the end
+ * of the active descriptor list, and increments the count of pending
+ * descriptors.
+ *
+ * The MXS platform DMA software imposes some rules on DMA commands to maintain
+ * important invariants. These rules are NOT checked, but they must be carefully
+ * applied by software that uses MXS DMA channels.
+ *
+ * Invariant:
+ * The DMA channel's hardware semaphore must reflect the number of DMA
+ * commands the hardware will process, but has not yet finished.
+ *
+ * Explanation:
+ * A DMA channel begins processing commands when its hardware semaphore is
+ * written with a value greater than zero, and it stops processing commands
+ * when the semaphore returns to zero.
+ *
+ * When a channel finishes a DMA command, it will decrement its semaphore if
+ * the DECREMENT_SEMAPHORE bit is set in that command's flags bits.
+ *
+ * In principle, it's not necessary for the DECREMENT_SEMAPHORE to be set,
+ * unless it suits the purposes of the software. For example, one could
+ * construct a series of five DMA commands, with the DECREMENT_SEMAPHORE
+ * bit set only in the last one. Then, setting the DMA channel's hardware
+ * semaphore to one would cause the entire series of five commands to be
+ * processed. However, this example would violate the invariant given above.
+ *
+ * Rule:
+ * ALL DMA commands MUST have the DECREMENT_SEMAPHORE bit set so that the DMA
+ * channel's hardware semaphore will be decremented EVERY time a command is
+ * processed.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @pdesc: A pointer to the new descriptor.
+ */
+extern int mxs_dma_desc_append(int channel, struct mxs_dma_desc *pdesc);
+
+/**
+ * mxs_dma_desc_add_list - Add a list of DMA descriptors to a channel.
+ *
+ * This function marks all the new descriptors as "ready," adds them to the end
+ * of the active descriptor list, and adds the length of the list to the count
+ * of pending descriptors.
+ *
+ * See mxs_dma_desc_append() for important rules that apply to incoming DMA
+ * descriptors.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @head: A pointer to the head of the list of DMA descriptors to add.
+ */
+extern int mxs_dma_desc_add_list(int channel, struct list_head *head);
+
+/**
+ * mxs_dma_desc_get_cooked - Retrieve processed DMA descriptors.
+ *
+ * This function moves all the descriptors from the DMA channel's "done" list to
+ * the head of the given list.
+ *
+ * @channel: The channel number. This is one of the globally unique DMA channel
+ * numbers given in mach/dma.h.
+ * @head: A pointer to the head of the list that will receive the
+ * descriptors on the "done" list.
+ */
+extern int mxs_dma_get_cooked(int channel, struct list_head *head);
+
+#endif