| 1 | /* |
| 2 | * Copyright 2010-2017 Intel Corporation. |
| 3 | * |
| 4 | * This program is free software; you can redistribute it and/or modify |
| 5 | * it under the terms of the GNU General Public License, version 2, |
| 6 | * as published by the Free Software Foundation. |
| 7 | * |
| 8 | * This program is distributed in the hope that it will be useful, |
| 9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 11 | * General Public License for more details. |
| 12 | * |
| 13 | * Disclaimer: The codes contained in these modules may be specific to |
| 14 | * the Intel Software Development Platform codenamed Knights Ferry, |
| 15 | * and the Intel product codenamed Knights Corner, and are not backward |
| 16 | * compatible with other Intel products. Additionally, Intel will NOT |
| 17 | * support the codes or instruction set in future products. |
| 18 | * |
| 19 | * Intel offers no warranty of any kind regarding the code. This code is |
| 20 | * licensed on an "AS IS" basis and Intel is not obligated to provide |
| 21 | * any support, assistance, installation, training, or other services |
| 22 | * of any kind. Intel is also not obligated to provide any updates, |
| 23 | * enhancements or extensions. Intel specifically disclaims any warranty |
| 24 | * of merchantability, non-infringement, fitness for any particular |
| 25 | * purpose, and any other warranty. |
| 26 | * |
| 27 | * Further, Intel disclaims all liability of any kind, including but |
| 28 | * not limited to liability for infringement of any proprietary rights, |
| 29 | * relating to the use of the code, even if Intel is notified of the |
| 30 | * possibility of such liability. Except as expressly stated in an Intel |
| 31 | * license agreement provided with this code and agreed upon with Intel, |
| 32 | * no license, express or implied, by estoppel or otherwise, to any |
| 33 | * intellectual property rights is granted herein. |
| 34 | */ |
| 35 | |
| 36 | #ifndef MIC_DMA_API_H |
| 37 | #define MIC_DMA_API_H |
| 38 | |
| 39 | struct dma_channel; |
| 40 | /* API exported by the DMA library */ |
| 41 | |
| 42 | /* |
| 43 | * Per MIC device (per MIC card) DMA handle. The card opens the handle to its own device. |
| 44 | * The host opens the handle to the DMA devices of one of the cards. |
| 45 | */ |
| 46 | typedef void * mic_dma_handle_t; |
| 47 | |
| 48 | /* DMA Library Init/Uninit Routines */ |
| 49 | int open_dma_device(int device_num, uint8_t *mmio_va_base, mic_dma_handle_t* dma_handle); |
| 50 | |
| 51 | void close_dma_device(int device_num, mic_dma_handle_t *dma_handle); |
| 52 | |
| 53 | /* |
| 54 | * reserve_dma_channel - reserve a given dma channel for exclusive use |
| 55 | * |
| 56 | * @dma_handle - handle to DMA device returned by open_dma_device |
| 57 | * @chan_num - Channel number to be reserved |
| 58 | * @chan - set to point to the dma channel reserved by the call |
| 59 | * |
| 60 | * Returns < 1 on error (errorno) |
| 61 | * Returns 0 on success |
| 62 | */ |
| 63 | int reserve_dma_channel(mic_dma_handle_t dma_handle, int chan_num, struct dma_channel **chan); |
| 64 | |
| 65 | /* |
| 66 | * allocate_dma_channel - dynamically allocate a dma channel (for a short while). Will |
| 67 | * search for, choose, and lock down one channel for use by the calling thread. |
| 68 | * |
| 69 | * @dma_handle - handle to DMA device returned by open_dma_device |
| 70 | * @chan - Returns the dma_channel pointer that was allocated by the call |
| 71 | * |
| 72 | * Returns < 1 on error |
| 73 | * Returns 0 on success |
| 74 | * |
| 75 | * NOTE: This function grabs a lock before exiting -- the calling thread MUST NOT |
| 76 | * sleep, and must call free_dma_channel before returning to user-space or switching |
| 77 | * volantarily to another thread. Similarly, this function cannot be called from |
| 78 | * an interrupt context at this time. |
| 79 | */ |
| 80 | int allocate_dma_channel(mic_dma_handle_t dma_handle, struct dma_channel **chan); |
| 81 | |
| 82 | /* |
| 83 | * request_dma_channel - Request a specific DMA channel. |
| 84 | * |
| 85 | * @dma_handle - handle to DMA device returned by open_dma_device |
| 86 | * @chan - Returns the dma_channel pointer that was requested |
| 87 | * |
| 88 | * Returns: 0 on success and -ERESTARTSYS if the wait was interrupted |
| 89 | * or -EBUSY if the channel was not available. |
| 90 | * |
| 91 | * NOTE: This function grabs a lock before exiting -- the calling thread MUST NOT |
| 92 | * sleep, and must call free_dma_channel before returning to user-space or switching |
| 93 | * volantarily to another thread. Similarly, this function cannot be called from |
| 94 | * an interrupt context at this time. |
| 95 | */ |
| 96 | int request_dma_channel(struct dma_channel *chan); |
| 97 | |
| 98 | /* |
| 99 | * free_dma_channel - after allocating a channel, used to |
| 100 | * free the channel after DMAs are submitted |
| 101 | * |
| 102 | * @chan - pointer to the dma_channel struct that was allocated |
| 103 | * |
| 104 | * Returns 0 on success, < 1 on error (errorno) |
| 105 | * |
| 106 | * NOTE: This function must be called after all do_dma calls are finished, |
| 107 | * but can be called before the DMAs actually complete (as long as the comp_cb() |
| 108 | * handler in do_dma don't refer to the dma_channel struct). If called with a |
| 109 | * dynamically allocated dma_channel, the caller must be the thread that called |
| 110 | * allocate_dma_channel. When operating on a dynamic channel, free unlocks the |
| 111 | * mutex locked in allocate. Statically allocated channels cannot be freed, |
| 112 | * and calling this function with that type of channel will return an error. |
| 113 | */ |
| 114 | int free_dma_channel(struct dma_channel *chan); |
| 115 | |
| 116 | /* |
| 117 | * drain_dma_poll - Drain all outstanding DMA operations for a particular |
| 118 | * DMA channel via polling. |
| 119 | * @chan - DMA channel |
| 120 | * Return 0 on success and -errno on error. |
| 121 | */ |
| 122 | int drain_dma_poll(struct dma_channel *chan); |
| 123 | |
| 124 | /* |
| 125 | * drain_dma_intr - Drain all outstanding DMA operations for a particular |
| 126 | * DMA channel via interrupt based blocking wait. |
| 127 | * @chan - DMA channel |
| 128 | * Return 0 on success and -errno on error. |
| 129 | */ |
| 130 | int drain_dma_intr(struct dma_channel *chan); |
| 131 | |
| 132 | /* |
| 133 | * drain_dma_global - Drain all outstanding DMA operations for |
| 134 | * all online DMA channel. |
| 135 | * @block - Is it okay to block while operations are drained? |
| 136 | * Return 0 on success and -errno on error. |
| 137 | */ |
| 138 | int drain_dma_global(mic_dma_handle_t dma_handle); |
| 139 | |
| 140 | #ifdef _MIC_SCIF_ |
| 141 | /* |
| 142 | * dma_suspend: DMA tasks before transition to low power state. |
| 143 | * @dma_handle: Handle for a DMA driver context. |
| 144 | */ |
| 145 | void dma_suspend(mic_dma_handle_t dma_handle); |
| 146 | |
| 147 | /* |
| 148 | * dma_resume: DMA tasks after wake up from low power state. |
| 149 | * @dma_handle: Handle for a DMA driver context. |
| 150 | */ |
| 151 | void dma_resume(mic_dma_handle_t dma_handle); |
| 152 | #else |
| 153 | /* |
| 154 | * dma_prep_suspend: DMA tasks required on host before a device can transition |
| 155 | * to a low power state. |
| 156 | * @dma_handle: Handle for a DMA driver context. |
| 157 | */ |
| 158 | void dma_prep_suspend(mic_dma_handle_t dma_handle); |
| 159 | #endif |
| 160 | |
| 161 | static inline void mic_dma_thread_free_chan(struct dma_channel *chan) |
| 162 | { |
| 163 | free_dma_channel(chan); |
| 164 | } |
| 165 | #ifndef _MIC_SCIF_ |
| 166 | //extern struct mutex lock_dma_dev_init; |
| 167 | void host_dma_interrupt_handler(mic_dma_handle_t dma_handle, uint32_t sboxSicr0Reg); |
| 168 | #endif |
| 169 | |
| 170 | #endif /* MIC_DMA_API_H */ |