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

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