sys/contrib/octeon-sdk/cvmx-dma-engine.h

   1 /***********************license start***************
   2  *  Copyright (c) 2003-2008 Cavium Networks (support@cavium.com). All rights
   3  *  reserved.
   4  *
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are
   8  *  met:
   9  *
  10  *      * Redistributions of source code must retain the above copyright
  11  *        notice, this list of conditions and the following disclaimer.
  12  *
  13  *      * Redistributions in binary form must reproduce the above
  14  *        copyright notice, this list of conditions and the following
  15  *        disclaimer in the documentation and/or other materials provided
  16  *        with the distribution.
  17  *
  18  *      * Neither the name of Cavium Networks nor the names of
  19  *        its contributors may be used to endorse or promote products
  20  *        derived from this software without specific prior written
  21  *        permission.
  22  *
  23  *  TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
  24  *  AND WITH ALL FAULTS AND CAVIUM NETWORKS MAKES NO PROMISES, REPRESENTATIONS
  25  *  OR WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH
  26  *  RESPECT TO THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY
  27  *  REPRESENTATION OR DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT
  28  *  DEFECTS, AND CAVIUM SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES
  29  *  OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR
  30  *  PURPOSE, LACK OF VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET
  31  *  POSSESSION OR CORRESPONDENCE TO DESCRIPTION.  THE ENTIRE RISK ARISING OUT
  32  *  OF USE OR PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
  33  *
  34  *
  35  *  For any questions regarding licensing please contact marketing@caviumnetworks.com
  36  *
  37  ***********************license end**************************************/
  38
  39
  40
  41
  42
  43
  44 /**
  45  * @file
  46  *
  47  * Interface to the PCI / PCIe DMA engines. These are only avialable
  48  * on chips with PCI / PCIe.
  49  *
  50  * <hr>$Revision: 41586 $<hr>
  51  */
  52
  53 #ifndef __CVMX_DMA_ENGINES_H__
  54 #define __CVMX_DMA_ENGINES_H__
  55
  56 #ifdef  __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 typedef enum
  61 {
  62     CVMX_DMA_ENGINE_TRANSFER_OUTBOUND = 0,  /**< OUTBOUND (read from L2/DRAM, write into PCI / PCIe memory space) */
  63     CVMX_DMA_ENGINE_TRANSFER_INBOUND = 1,   /**< INBOUND (read from PCI / PCIe memory space, write into L2/DRAM) */
  64     CVMX_DMA_ENGINE_TRANSFER_INTERNAL = 2,  /**< INTERNAL-ONLY (read from L2/DRAM, write into L2/DRAM). Only available on chips with PCIe */
  65     CVMX_DMA_ENGINE_TRANSFER_EXTERNAL = 3,  /**< EXTERNAL-ONLY (read from PCIe memory space, write into PCIe memory space). Only available on chips with PCIe */
  66 } cvmx_dma_engine_transfer_t;
  67
  68 typedef union
  69 {
  70     uint64_t u64;
  71     struct
  72     {
  73         uint64_t    reserved_60_63 :   4;   /**< Must be zero */
  74         uint64_t    fport           :  2;   /**< First port. FPort indicates the physical PCIe port used for the
  75                                                 PCIe memory space pointers in the FIRST POINTERS block in the
  76                                                 EXTERNAL-ONLY case. Must be zero in the OUTBOUND, INBOUND and
  77                                                 INTERNAL-ONLY cases. Must be zero on chips with PCI */
  78         uint64_t    lport           :  2;   /**< Last port. LPort indicates the physical PCIe port used for the
  79                                                 PCIe memory space pointers in the LAST POINTERS block in the
  80                                                 OUTBOUND, INBOUND, and EXTERNAL-ONLY cases. Must be zero in the
  81                                                 INTERNAL-ONLY case. Must be zero on chips with PCI */
  82         cvmx_dma_engine_transfer_t type :  2; /**< Type  A given PCI DMA transfer is either OUTBOUND (read from L2/DRAM,
  83                                                 write into PCI / PCIe memory space), INBOUND (read from PCI / PCIe memory space, write
  84                                                 into L2/DRAM), INTERNAL-ONLY (read from L2/DRAM, write into L2/DRAM), or
  85                                                 EXTERNAL-ONLY (read from PCIe memory space, write into PCIe memory space). */
  86         uint64_t    wqp             :  1;   /**< Work-queue pointer. When WQP = 1, PTR (if non-zero) is a pointer to a
  87                                                 work-queue entry that is submitted by the hardware after completing the DMA;
  88                                                 when WQP = 0, PTR (if non-zero) is a pointer to a byte in local memory that
  89                                                 is written to 0 by the hardware after completing the DMA. */
  90         uint64_t    c               :  1;   /**< C  Counter. 1 = use counter 1, 0 = use counter 0.
  91                                                 The C bit selects between the two counters (NPEI_DMA_CNTS[DMA0,DMA1])
  92                                                 that can optionally be updated after an OUTBOUND or EXTERNAL-ONLY
  93                                                 transfer, and also selects between the two forced-interrupt bits
  94                                                 (NPEI_INT_SUMn[DMA0_FI, DMA1_FI]) that can optionally be set after an
  95                                                 OUTBOUND or EXTERNAL-ONLY transfer. C must be zero for INBOUND or
  96                                                 INTERNAL-ONLY transfers. */
  97         uint64_t    ca              :  1;   /**< CA  Counter add.
  98                                                 When CA = 1, the hardware updates the selected counter after it completes the
  99                                                 PCI DMA OUTBOUND or EXTERNAL-ONLY Instruction.
 100                                                     - If C = 0, PCIE_DMA_CNT0 is updated
 101                                                     - If C = 1, PCIE_DMA_CNT1 is updated.
 102                                                 Note that this update may indirectly cause
 103                                                 NPEI_INT_SUM[DCNT0,DCNT1,DTIME0,DTIME1] to become set (depending
 104                                                 on the NPEI_DMA*_INT_LEVEL settings), so may cause interrupts to occur on a
 105                                                 remote PCI host.
 106                                                     - If NPEI_DMA_CONTROL[O_ADD1] = 1, the counter is updated by 1.
 107                                                     - If NPEI_DMA_CONTROL[O_ADD1] = 0, the counter is updated by the total
 108                                                     bytes in the transfer.
 109                                                 When CA = 0, the hardware does not update any counters.
 110                                                 For an INBOUND or INTERNAL-ONLY PCI DMA transfer, CA must never be
 111                                                 set, and the hardware never adds to the counters. */
 112         uint64_t    fi              :  1;   /**< FI  Force interrupt.
 113                                                 When FI is set for an OUTBOUND or EXTERNAL-ONLY transfer, the hardware
 114                                                 sets a forced interrupt bit after it completes the PCI DMA Instruction. If C = 0,
 115                                                 NPEI_INT_SUMn[DMA0_FI] is set, else NPEI_INT_SUMn[DMA1_FI] is set. For
 116                                                 an INBOUND or INTERNAL-ONLY PCI DMA operation, FI must never be set,
 117                                                 and the hardware never generates interrupts. */
 118         uint64_t    ii              :  1;   /**< II Ignore the I bit (i.e. the I bit of the PCI DMA instruction local pointer).
 119                                                 For OUTBOUND transfers when II = 1, ignore the I bit and the FL bit in the
 120                                                 DMA HDR alone determines whether the hardware frees any/all of the local
 121                                                 buffers in the FIRST POINTERS area:
 122                                                     - when FL = 1, the hardware frees the local buffer when II=1.
 123                                                     - when FL = 0, the hardware does not free the local buffer when II=1.
 124                                                 For OUTBOUND transfers when II = 0, the I bit in the local pointer selects
 125                                                 whether local buffers are freed on a pointer-by-pointer basis:
 126                                                     - when (FL  I) is true, the hardware frees the local buffer when II=0.
 127                                                 For INBOUND, INTERNAL-ONLY, and EXTERNAL-ONLY PCI DMA transfers,
 128                                                 II must never be set, and local buffers are never freed. */
 129         uint64_t    fl              :  1;   /**< FL  Free local buffer.
 130                                                 When FL = 1, for an OUTBOUND operation, it indicates that the local buffers in
 131                                                 the FIRST BUFFERS area should be freed.
 132                                                 If II = 1, the FL bit alone indicates whether the local buffer should be freed:
 133                                                     - when FL = 1, the hardware frees the local buffer when II=1.
 134                                                     - when FL = 0, the hardware does not free the local buffer when II=1.
 135                                                 If II = 0, the I bit in the local pointer (refer to Section 9.5.2) determines whether
 136                                                 the local buffer is freed:
 137                                                     - when (FL  I) is true, the hardware frees the local buffer when II=0.
 138                                                 For an INBOUND, INTERNAL-ONLY, or EXTERNAL-ONLY PCI DMA transfer,
 139                                                 FL must never be set, and local buffers are never freed. */
 140         uint64_t    nlst            :  4;   /**< NLST  Number Last pointers.
 141                                                 The number of pointers in the LAST POINTERS area.
 142                                                 In the INBOUND, OUTBOUND, and EXTERNAL-ONLY cases, the LAST
 143                                                 POINTERS area contains PCI components, and the number of 64-bit words
 144                                                 required in the LAST POINTERS area is:
 145                                                     - HDR.NLST + ((HDR.NLST + 3)/4) where the division removes the fraction.
 146                                                 In the INTERNAL-ONLY case, the LAST POINTERS area contains local
 147                                                 pointers, and the number of 64-bit words required in the LAST POINTERS area is:
 148                                                     - HDR.NLST
 149                                                 Note that the sum of the number of 64-bit words in the LAST POINTERS and
 150                                                 FIRST POINTERS area must never exceed 31. */
 151         uint64_t    nfst            :  4;   /**< NFST  Number First pointers.
 152                                                 The number of pointers in the FIRST POINTERS area.
 153                                                 In the INBOUND, OUTBOUND, and INTERNAL-ONLY cases, the FIRST
 154                                                 POINTERS area contains local pointers, and the number of 64-bit words required
 155                                                 in the FIRST POINTERS area is:
 156                                                     - HDR.NFST
 157                                                 In the EXTERNAL-ONLY case, the FIRST POINTERS area contains PCI
 158                                                 components, and the number of 64-bit words required in the FIRST POINTERS
 159                                                 area is:
 160                                                     - HDR.NFST + ((HDR.NFST + 3)/4) where the division removes the fraction. */
 161         uint64_t    addr            : 40;   /**< PTR  Pointer, either a work-queue-entry pointer (when WQP = 1) or a local
 162                                                 memory pointer (WQP = 0).
 163                                                 When WQP = 1 and PTR  0x0, the hardware inserts the work-queue entry
 164                                                 indicated by PTR into a POW input queue after the PCI DMA operation is
 165                                                 complete. (Section 5.4 describes the work queue entry requirements in this
 166                                                 case.) When WQP = 1, PTR<2:0> must be 0x0.
 167                                                 When WQP = 0 and PTR  0x0, the hardware writes the single byte in local
 168                                                 memory indicated by PTR to 0x0 after the PCI DMA operation is complete.
 169                                                 NPEI_DMA_CONTROL[B0_LEND] selects the endian-ness of PTR in this
 170                                                 case.
 171                                                 When PTR = 0x0, the hardware performs no operation after the PCI DMA
 172                                                 operation is complete. */
 173     } s;
 174 } cvmx_dma_engine_header_t;
 175
 176 typedef union
 177 {
 178     uint64_t u64;
 179     struct
 180     {
 181         uint64_t    i               :  1;   /**< I  Invert free.
 182                                                 This bit gives the software the ability to free buffers independently for an
 183                                                 OUTBOUND PCI DMA transfer. I is not used by the hardware when II is set. I
 184                                                 must not be set, and buffers are never freed, for INBOUND, INTERNAL-ONLY,
 185                                                 and EXTERNAL-ONLY PCI DMA transfers. */
 186         uint64_t    back            :  4;   /**< Back  Backup amount.
 187                                                 Allows the start of a buffer that is to be freed during an OUTBOUND transfer to
 188                                                 be different from the ptr value. Back specifies the amount to subtract from the
 189                                                 pointer to reach the start when freeing a buffer.
 190                                                 The address that is the start of the buffer being freed is:
 191                                                     - Buffer start address = ((ptr >> 7) - Back) << 7.
 192                                                 Back is only used by the hardware when the buffer corresponding to ptr is freed.
 193                                                 Back must be 0x0, and buffers are never freed, for INBOUND, INTERNAL-ONLY,
 194                                                 and EXTERNAL-ONLY PCI DMA transfers. */
 195         uint64_t    pool            :  3;   /**< Pool  Free pool.
 196                                                 Specifies which pool (of the eight hardware-managed FPA free pools) receives the
 197                                                 buffer associated with ptr when freed during an OUTBOUND transfer.
 198                                                 Pool is only used when the buffer corresponding to ptr is freed. Pool must be 0x0,
 199                                                 and buffers are never freed, for INBOUND, INTERNAL-ONLY, and EXTERNAL-ONLY
 200                                                 PCI DMA transfers. */
 201         uint64_t    f               :  1;   /**< F  Full-block writes are allowed.
 202                                                 When set, the hardware is permitted to write all the bytes in the cache blocks
 203                                                 covered by ptr, ptr + Size - 1. This can improve memory system performance
 204                                                 when the write misses in the L2 cache.
 205                                                 F can only be set for local pointers that can be written to:
 206                                                     - The local pointers in the FIRST POINTERS area that are write pointers for
 207                                                     INBOUND transfers.
 208                                                     - The local pointers in the LAST POINTERS area that are always write
 209                                                     pointers (when present for INTERNAL-ONLY transfers).
 210                                                 F must not be set for local pointers that are not written to:
 211                                                     - The local pointers in the FIRST POINTERS area for OUTBOUND and
 212                                                     INTERNAL-ONLY transfers. */
 213         uint64_t    a               :  1;   /**< A  Allocate L2.
 214                                                 This is a hint to the hardware that the cache blocks should be allocated in the L2
 215                                                 cache (if they were not already). */
 216         uint64_t    l               :  1;   /**< L  Little-endian.
 217                                                 When L is set, the data at ptr is in little-endian format rather than big-endian. */
 218         uint64_t    size            : 13;   /**< Size  Size in bytes of the contiguous space specified by ptr. A Size value of 0 is
 219                                                 illegal. Note that the sum of the sizes in the FIRST POINTERS area must always
 220                                                 exactly equal the sum of the sizes/lengths in the LAST POINTERS area:
 221                                                     - In the OUTBOUND and INBOUND cases, the HDR.NFST size fields in the
 222                                                     local pointers in the FIRST POINTERS area must exactly equal the lengths
 223                                                     of the HDR.NLST fragments in the PCI components in the LAST POINTERS
 224                                                     area.
 225                                                     - In the INTERNAL-ONLY case, the HDR.NFST size fields in the local
 226                                                     pointers in the FIRST POINTERS area must equal the HDR.NLST size
 227                                                     fields in the local pointers in the LAST POINTERS area. */
 228         uint64_t    reserved_36_39  :  4;   /**< Must be zero */
 229         uint64_t    addr            : 36;   /**< L2/DRAM byte pointer. Points to where the packet data starts.
 230                                                 Ptr can be any byte alignment. Note that ptr is interpreted as a big-endian byte
 231                                                 pointer when L is clear, a little-endian byte pointer when L is set. */
 232     } internal;
 233     struct
 234     {
 235         uint64_t    len0            : 16;   /**< Length of PCI / PCIe memory for address 0 */
 236         uint64_t    len1            : 16;   /**< Length of PCI / PCIe memory for address 1 */
 237         uint64_t    len2            : 16;   /**< Length of PCI / PCIe memory for address 2 */
 238         uint64_t    len3            : 16;   /**< Length of PCI / PCIe memory for address 3 */
 239     } pcie_length;
 240 } cvmx_dma_engine_buffer_t;
 241
 242 /**
 243  * Initialize the DMA engines for use
 244  *
 245  * @return Zero on success, negative on failure
 246  */
 247 int cvmx_dma_engine_initialize(void);
 248
 249 /**
 250  * Shutdown all DMA engines. The engeines must be idle when this
 251  * function is called.
 252  *
 253  * @return Zero on success, negative on failure
 254  */
 255 int cvmx_dma_engine_shutdown(void);
 256
 257 /**
 258  * Return the number of DMA engimes supported by this chip
 259  *
 260  * @return Number of DMA engines
 261  */
 262 int cvmx_dma_engine_get_num(void);
 263
 264 /**
 265  * Submit a series of DMA comamnd to the DMA engines.
 266  *
 267  * @param engine  Engine to submit to (0-4)
 268  * @param header  Command header
 269  * @param num_buffers
 270  *                The number of data pointers
 271  * @param buffers Comamnd data pointers
 272  *
 273  * @return Zero on success, negative on failure
 274  */
 275 int cvmx_dma_engine_submit(int engine, cvmx_dma_engine_header_t header, int num_buffers, cvmx_dma_engine_buffer_t buffers[]);
 276
 277 /**
 278  * Build the first and last pointers based on a DMA engine header
 279  * and submit them to the engine. The purpose of this function is
 280  * to simplify the building of DMA engine commands by automatically
 281  * converting a simple address and size into the apropriate internal
 282  * or PCI / PCIe address list. This function does not support gather lists,
 283  * so you will need to build your own lists in that case.
 284  *
 285  * @param engine Engine to submit to (0-4)
 286  * @param header DMA Command header. Note that the nfst and nlst fields do not
 287  *               need to be filled in. All other fields must be set properly.
 288  * @param first_address
 289  *               Address to use for the first pointers. In the case of INTERNAL,
 290  *               INBOUND, and OUTBOUND this is an Octeon memory address. In the
 291  *               case of EXTERNAL, this is the source PCI / PCIe address.
 292  * @param last_address
 293  *               Address to use for the last pointers. In the case of EXTERNAL,
 294  *               INBOUND, and OUTBOUND this is a PCI / PCIe address. In the
 295  *               case of INTERNAL, this is the Octeon memory destination address.
 296  * @param size   Size of the transfer to perform.
 297  *
 298  * @return Zero on success, negative on failure
 299  */
 300 int cvmx_dma_engine_transfer(int engine, cvmx_dma_engine_header_t header,
 301                              uint64_t first_address, uint64_t last_address,
 302                              int size);
 303
 304 /**
 305  * Simplified interface to the DMA engines to emulate memcpy()
 306  *
 307  * @param engine Engine to submit to (0-4)
 308  * @param dest   Pointer to the destination memory. cvmx_ptr_to_phys() will be
 309  *               used to turn this into a physical address. It cannot be a local
 310  *               or CVMX_SHARED block.
 311  * @param source Pointer to the source memory.
 312  *               cvmx_ptr_to_phys() will be used to turn this
 313  *               into a physical address. It cannot be a local
 314  *               or CVMX_SHARED block.
 315  * @param length Number of bytes to copy
 316  *
 317  * @return Zero on success, negative on failure
 318  */
 319 static inline int cvmx_dma_engine_memcpy(int engine, void *dest, void *source, int length)
 320 {
 321     cvmx_dma_engine_header_t header;
 322     header.u64 = 0;
 323     header.s.type = CVMX_DMA_ENGINE_TRANSFER_INTERNAL;
 324     return cvmx_dma_engine_transfer(engine, header, cvmx_ptr_to_phys(source),
 325                                     cvmx_ptr_to_phys(dest), length);
 326 }
 327
 328 #ifdef  __cplusplus
 329 }
 330 #endif
 331
 332 #endif // __CVMX_CMD_QUEUE_H__