arch/tile/include/gxio/trio.h

   1 /*
   2  * Copyright 2012 Tilera Corporation. All Rights Reserved.
   3  *
   4  *   This program is free software; you can redistribute it and/or
   5  *   modify it under the terms of the GNU General Public License
   6  *   as published by the Free Software Foundation, version 2.
   7  *
   8  *   This program is distributed in the hope that it will be useful, but
   9  *   WITHOUT ANY WARRANTY; without even the implied warranty of
  10  *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
  11  *   NON INFRINGEMENT.  See the GNU General Public License for
  12  *   more details.
  13  */
  14
  15 /*
  16  *
  17  * An API for allocating, configuring, and manipulating TRIO hardware
  18  * resources
  19  */
  20
  21 /*
  22  *
  23  * The TILE-Gx TRIO shim provides connections to external devices via
  24  * PCIe or other transaction IO standards.  The gxio_trio_ API,
  25  * declared in <gxio/trio.h>, allows applications to allocate and
  26  * configure TRIO IO resources like DMA command rings, memory map
  27  * windows, and device interrupts.  The following sections introduce
  28  * the various components of the API.  We strongly recommend reading
  29  * the TRIO section of the IO Device Guide (UG404) before working with
  30  * this API.
  31  *
  32  * @section trio__ingress TRIO Ingress Hardware Resources
  33  *
  34  * The TRIO ingress hardware is responsible for examining incoming
  35  * PCIe or StreamIO packets and choosing a processing mechanism based
  36  * on the packets' bus address.  The gxio_trio_ API can be used to
  37  * configure different handlers for different ranges of bus address
  38  * space.  The user can configure "mapped memory" and "scatter queue"
  39  * regions to match incoming packets within 4kB-aligned ranges of bus
  40  * addresses.  Each range specifies a different set of mapping
  41  * parameters to be applied when handling the ingress packet.  The
  42  * following sections describe how to work with MapMem and scatter
  43  * queue regions.
  44  *
  45  * @subsection trio__mapmem TRIO MapMem Regions
  46  *
  47  * TRIO mapped memory (or MapMem) regions allow the user to map
  48  * incoming read and write requests directly to the application's
  49  * memory space.  MapMem regions are allocated via
  50  * gxio_trio_alloc_memory_maps().  Given an integer MapMem number,
  51  * applications can use gxio_trio_init_memory_map() to specify the
  52  * range of bus addresses that will match the region and the range of
  53  * virtual addresses to which those packets will be applied.
  54  *
  55  * As with many other gxio APIs, the programmer must be sure to
  56  * register memory pages that will be used with MapMem regions.  Pages
  57  * can be registered with TRIO by allocating an ASID (address space
  58  * identifier) and then using gxio_trio_register_page() to register up to
  59  * 16 pages with the hardware.  The initialization functions for
  60  * resources that require registered memory (MapMem, scatter queues,
  61  * push DMA, and pull DMA) then take an 'asid' parameter in order to
  62  * configure which set of registered pages is used by each resource.
  63  *
  64  * @subsection trio__scatter_queue TRIO Scatter Queues
  65  *
  66  * The TRIO shim's scatter queue regions allow users to dynamically
  67  * map buffers from a large address space into a small range of bus
  68  * addresses.  This is particularly helpful for PCIe endpoint devices,
  69  * where the host generally limits the size of BARs to tens of
  70  * megabytes.
  71  *
  72  * Each scatter queue consists of a memory map region, a queue of
  73  * tile-side buffer VAs to be mapped to that region, and a bus-mapped
  74  * "doorbell" register that the remote endpoint can write to trigger a
  75  * dequeue of the current buffer VA, thus swapping in a new buffer.
  76  * The VAs pushed onto a scatter queue must be 4kB aligned, so
  77  * applications may need to use higher-level protocols to inform
  78  * remote entities that they should apply some additional, sub-4kB
  79  * offset when reading or writing the scatter queue region.  For more
  80  * information, see the IO Device Guide (UG404).
  81  *
  82  * @section trio__egress TRIO Egress Hardware Resources
  83  *
  84  * The TRIO shim supports two mechanisms for egress packet generation:
  85  * programmed IO (PIO) and push/pull DMA.  PIO allows applications to
  86  * create MMIO mappings for PCIe or StreamIO address space, such that
  87  * the application can generate word-sized read or write transactions
  88  * by issuing load or store instructions.  Push and pull DMA are tuned
  89  * for larger transactions; they use specialized hardware engines to
  90  * transfer large blocks of data at line rate.
  91  *
  92  * @subsection trio__pio TRIO Programmed IO
  93  *
  94  * Programmed IO allows applications to create MMIO mappings for PCIe
  95  * or StreamIO address space.  The hardware PIO regions support access
  96  * to PCIe configuration, IO, and memory space, but the gxio_trio API
  97  * only supports memory space accesses.  PIO regions are allocated
  98  * with gxio_trio_alloc_pio_regions() and initialized via
  99  * gxio_trio_init_pio_region().  Once a region is bound to a range of
 100  * bus address via the initialization function, the application can
 101  * use gxio_trio_map_pio_region() to create MMIO mappings from its VA
 102  * space onto the range of bus addresses supported by the PIO region.
 103  *
 104  * @subsection trio_dma TRIO Push and Pull DMA
 105  *
 106  * The TRIO push and pull DMA engines allow users to copy blocks of
 107  * data between application memory and the bus.  Push DMA generates
 108  * write packets that copy from application memory to the bus and pull
 109  * DMA generates read packets that copy from the bus into application
 110  * memory.  The DMA engines are managed via an API that is very
 111  * similar to the mPIPE eDMA interface.  For a detailed explanation of
 112  * the eDMA queue API, see @ref gxio_mpipe_wrappers.
 113  *
 114  * Push and pull DMA queues are allocated via
 115  * gxio_trio_alloc_push_dma_ring() / gxio_trio_alloc_pull_dma_ring().
 116  * Once allocated, users generally use a ::gxio_trio_dma_queue_t
 117  * object to manage the queue, providing easy wrappers for reserving
 118  * command slots in the DMA command ring, filling those slots, and
 119  * waiting for commands to complete.  DMA queues can be initialized
 120  * via gxio_trio_init_push_dma_queue() or
 121  * gxio_trio_init_pull_dma_queue().
 122  *
 123  * See @ref trio/push_dma/app.c for an example of how to use push DMA.
 124  *
 125  * @section trio_shortcomings Plans for Future API Revisions
 126  *
 127  * The simulation framework is incomplete.  Future features include:
 128  *
 129  * - Support for reset and deallocation of resources.
 130  *
 131  * - Support for pull DMA.
 132  *
 133  * - Support for interrupt regions and user-space interrupt delivery.
 134  *
 135  * - Support for getting BAR mappings and reserving regions of BAR
 136  *   address space.
 137  */
 138 #ifndef _GXIO_TRIO_H_
 139 #define _GXIO_TRIO_H_
 140
 141 #include <linux/types.h>
 142
 143 #include <gxio/common.h>
 144 #include <gxio/dma_queue.h>
 145
 146 #include <arch/trio_constants.h>
 147 #include <arch/trio.h>
 148 #include <arch/trio_pcie_intfc.h>
 149 #include <arch/trio_pcie_rc.h>
 150 #include <arch/trio_shm.h>
 151 #include <hv/drv_trio_intf.h>
 152 #include <hv/iorpc.h>
 153
 154 /* A context object used to manage TRIO hardware resources. */
 155 typedef struct {
 156
 157         /* File descriptor for calling up to Linux (and thus the HV). */
 158         int fd;
 159
 160         /* The VA at which the MAC MMIO registers are mapped. */
 161         char *mmio_base_mac;
 162
 163         /* The VA at which the PIO config space are mapped for each PCIe MAC.
 164            Gx36 has max 3 PCIe MACs per TRIO shim. */
 165         char *mmio_base_pio_cfg[TILEGX_TRIO_PCIES];
 166
 167 #ifdef USE_SHARED_PCIE_CONFIG_REGION
 168         /* Index of the shared PIO region for PCI config access. */
 169         int pio_cfg_index;
 170 #else
 171         /* Index of the PIO region for PCI config access per MAC. */
 172         int pio_cfg_index[TILEGX_TRIO_PCIES];
 173 #endif
 174
 175         /*  The VA at which the push DMA MMIO registers are mapped. */
 176         char *mmio_push_dma[TRIO_NUM_PUSH_DMA_RINGS];
 177
 178         /*  The VA at which the pull DMA MMIO registers are mapped. */
 179         char *mmio_pull_dma[TRIO_NUM_PUSH_DMA_RINGS];
 180
 181         /* Application space ID. */
 182         unsigned int asid;
 183
 184 } gxio_trio_context_t;
 185
 186 /* Command descriptor for push or pull DMA. */
 187 typedef TRIO_DMA_DESC_t gxio_trio_dma_desc_t;
 188
 189 /* A convenient, thread-safe interface to an eDMA ring. */
 190 typedef struct {
 191
 192         /* State object for tracking head and tail pointers. */
 193         __gxio_dma_queue_t dma_queue;
 194
 195         /* The ring entries. */
 196         gxio_trio_dma_desc_t *dma_descs;
 197
 198         /* The number of entries minus one. */
 199         unsigned long mask_num_entries;
 200
 201         /* The log2() of the number of entries. */
 202         unsigned int log2_num_entries;
 203
 204 } gxio_trio_dma_queue_t;
 205
 206 /* Initialize a TRIO context.
 207  *
 208  * This function allocates a TRIO "service domain" and maps the MMIO
 209  * registers into the the caller's VA space.
 210  *
 211  * @param trio_index Which TRIO shim; Gx36 must pass 0.
 212  * @param context Context object to be initialized.
 213  */
 214 extern int gxio_trio_init(gxio_trio_context_t *context,
 215                           unsigned int trio_index);
 216
 217 /* This indicates that an ASID hasn't been allocated. */
 218 #define GXIO_ASID_NULL -1
 219
 220 /* Ordering modes for map memory regions and scatter queue regions. */
 221 typedef enum gxio_trio_order_mode_e {
 222         /* Writes are not ordered.  Reads always wait for previous writes. */
 223         GXIO_TRIO_ORDER_MODE_UNORDERED =
 224                 TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_UNORDERED,
 225         /* Both writes and reads wait for previous transactions to complete. */
 226         GXIO_TRIO_ORDER_MODE_STRICT =
 227                 TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_STRICT,
 228         /* Writes are ordered unless the incoming packet has the
 229            relaxed-ordering attributes set. */
 230         GXIO_TRIO_ORDER_MODE_OBEY_PACKET =
 231                 TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_REL_ORD
 232 } gxio_trio_order_mode_t;
 233
 234 /* Initialize a memory mapping region.
 235  *
 236  * @param context An initialized TRIO context.
 237  * @param map A Memory map region allocated by gxio_trio_alloc_memory_map().
 238  * @param target_mem VA of backing memory, should be registered via
 239  *   gxio_trio_register_page() and aligned to 4kB.
 240  * @param target_size Length of the memory mapping, must be a multiple
 241  * of 4kB.
 242  * @param asid ASID to be used for Tile-side address translation.
 243  * @param mac MAC number.
 244  * @param bus_address Bus address at which the mapping starts.
 245  * @param order_mode Memory ordering mode for this mapping.
 246  * @return Zero on success, else ::GXIO_TRIO_ERR_BAD_MEMORY_MAP,
 247  * GXIO_TRIO_ERR_BAD_ASID, or ::GXIO_TRIO_ERR_BAD_BUS_RANGE.
 248  */
 249 extern int gxio_trio_init_memory_map(gxio_trio_context_t *context,
 250                                      unsigned int map, void *target_mem,
 251                                      size_t target_size, unsigned int asid,
 252                                      unsigned int mac, uint64_t bus_address,
 253                                      gxio_trio_order_mode_t order_mode);
 254
 255 /* Flags that can be passed to resource allocation functions. */
 256 enum gxio_trio_alloc_flags_e {
 257         GXIO_TRIO_ALLOC_FIXED = HV_TRIO_ALLOC_FIXED,
 258 };
 259
 260 /* Flags that can be passed to memory registration functions. */
 261 enum gxio_trio_mem_flags_e {
 262         /* Do not fill L3 when writing, and invalidate lines upon egress. */
 263         GXIO_TRIO_MEM_FLAG_NT_HINT = IORPC_MEM_BUFFER_FLAG_NT_HINT,
 264
 265         /* L3 cache fills should only populate IO cache ways. */
 266         GXIO_TRIO_MEM_FLAG_IO_PIN = IORPC_MEM_BUFFER_FLAG_IO_PIN,
 267 };
 268
 269 /* Flag indicating a request generator uses a special traffic
 270     class. */
 271 #define GXIO_TRIO_FLAG_TRAFFIC_CLASS(N) HV_TRIO_FLAG_TC(N)
 272
 273 /* Flag indicating a request generator uses a virtual function
 274     number. */
 275 #define GXIO_TRIO_FLAG_VFUNC(N) HV_TRIO_FLAG_VFUNC(N)
 276
 277 /*****************************************************************
 278  *                       Memory Registration                      *
 279  ******************************************************************/
 280
 281 /* Allocate Application Space Identifiers (ASIDs).  Each ASID can
 282  * register up to 16 page translations.  ASIDs are used by memory map
 283  * regions, scatter queues, and DMA queues to translate application
 284  * VAs into memory system PAs.
 285  *
 286  * @param context An initialized TRIO context.
 287  * @param count Number of ASIDs required.
 288  * @param first Index of first ASID if ::GXIO_TRIO_ALLOC_FIXED flag
 289  *   is set, otherwise ignored.
 290  * @param flags Flag bits, including bits from ::gxio_trio_alloc_flags_e.
 291  * @return Index of first ASID, or ::GXIO_TRIO_ERR_NO_ASID if allocation
 292  *   failed.
 293  */
 294 extern int gxio_trio_alloc_asids(gxio_trio_context_t *context,
 295                                  unsigned int count, unsigned int first,
 296                                  unsigned int flags);
 297
 298 #endif /* ! _GXIO_TRIO_H_ */