diff options
Diffstat (limited to 'arch/tile/include/gxio/trio.h')
| -rw-r--r-- | arch/tile/include/gxio/trio.h | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/arch/tile/include/gxio/trio.h b/arch/tile/include/gxio/trio.h deleted file mode 100644 index df10a662cc25..000000000000 --- a/arch/tile/include/gxio/trio.h +++ /dev/null @@ -1,298 +0,0 @@ -/* - * Copyright 2012 Tilera Corporation. 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, version 2. - * - * 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, GOOD TITLE or - * NON INFRINGEMENT. See the GNU General Public License for - * more details. - */ - -/* - * - * An API for allocating, configuring, and manipulating TRIO hardware - * resources - */ - -/* - * - * The TILE-Gx TRIO shim provides connections to external devices via - * PCIe or other transaction IO standards. The gxio_trio_ API, - * declared in <gxio/trio.h>, allows applications to allocate and - * configure TRIO IO resources like DMA command rings, memory map - * windows, and device interrupts. The following sections introduce - * the various components of the API. We strongly recommend reading - * the TRIO section of the IO Device Guide (UG404) before working with - * this API. - * - * @section trio__ingress TRIO Ingress Hardware Resources - * - * The TRIO ingress hardware is responsible for examining incoming - * PCIe or StreamIO packets and choosing a processing mechanism based - * on the packets' bus address. The gxio_trio_ API can be used to - * configure different handlers for different ranges of bus address - * space. The user can configure "mapped memory" and "scatter queue" - * regions to match incoming packets within 4kB-aligned ranges of bus - * addresses. Each range specifies a different set of mapping - * parameters to be applied when handling the ingress packet. The - * following sections describe how to work with MapMem and scatter - * queue regions. - * - * @subsection trio__mapmem TRIO MapMem Regions - * - * TRIO mapped memory (or MapMem) regions allow the user to map - * incoming read and write requests directly to the application's - * memory space. MapMem regions are allocated via - * gxio_trio_alloc_memory_maps(). Given an integer MapMem number, - * applications can use gxio_trio_init_memory_map() to specify the - * range of bus addresses that will match the region and the range of - * virtual addresses to which those packets will be applied. - * - * As with many other gxio APIs, the programmer must be sure to - * register memory pages that will be used with MapMem regions. Pages - * can be registered with TRIO by allocating an ASID (address space - * identifier) and then using gxio_trio_register_page() to register up to - * 16 pages with the hardware. The initialization functions for - * resources that require registered memory (MapMem, scatter queues, - * push DMA, and pull DMA) then take an 'asid' parameter in order to - * configure which set of registered pages is used by each resource. - * - * @subsection trio__scatter_queue TRIO Scatter Queues - * - * The TRIO shim's scatter queue regions allow users to dynamically - * map buffers from a large address space into a small range of bus - * addresses. This is particularly helpful for PCIe endpoint devices, - * where the host generally limits the size of BARs to tens of - * megabytes. - * - * Each scatter queue consists of a memory map region, a queue of - * tile-side buffer VAs to be mapped to that region, and a bus-mapped - * "doorbell" register that the remote endpoint can write to trigger a - * dequeue of the current buffer VA, thus swapping in a new buffer. - * The VAs pushed onto a scatter queue must be 4kB aligned, so - * applications may need to use higher-level protocols to inform - * remote entities that they should apply some additional, sub-4kB - * offset when reading or writing the scatter queue region. For more - * information, see the IO Device Guide (UG404). - * - * @section trio__egress TRIO Egress Hardware Resources - * - * The TRIO shim supports two mechanisms for egress packet generation: - * programmed IO (PIO) and push/pull DMA. PIO allows applications to - * create MMIO mappings for PCIe or StreamIO address space, such that - * the application can generate word-sized read or write transactions - * by issuing load or store instructions. Push and pull DMA are tuned - * for larger transactions; they use specialized hardware engines to - * transfer large blocks of data at line rate. - * - * @subsection trio__pio TRIO Programmed IO - * - * Programmed IO allows applications to create MMIO mappings for PCIe - * or StreamIO address space. The hardware PIO regions support access - * to PCIe configuration, IO, and memory space, but the gxio_trio API - * only supports memory space accesses. PIO regions are allocated - * with gxio_trio_alloc_pio_regions() and initialized via - * gxio_trio_init_pio_region(). Once a region is bound to a range of - * bus address via the initialization function, the application can - * use gxio_trio_map_pio_region() to create MMIO mappings from its VA - * space onto the range of bus addresses supported by the PIO region. - * - * @subsection trio_dma TRIO Push and Pull DMA - * - * The TRIO push and pull DMA engines allow users to copy blocks of - * data between application memory and the bus. Push DMA generates - * write packets that copy from application memory to the bus and pull - * DMA generates read packets that copy from the bus into application - * memory. The DMA engines are managed via an API that is very - * similar to the mPIPE eDMA interface. For a detailed explanation of - * the eDMA queue API, see @ref gxio_mpipe_wrappers. - * - * Push and pull DMA queues are allocated via - * gxio_trio_alloc_push_dma_ring() / gxio_trio_alloc_pull_dma_ring(). - * Once allocated, users generally use a ::gxio_trio_dma_queue_t - * object to manage the queue, providing easy wrappers for reserving - * command slots in the DMA command ring, filling those slots, and - * waiting for commands to complete. DMA queues can be initialized - * via gxio_trio_init_push_dma_queue() or - * gxio_trio_init_pull_dma_queue(). - * - * See @ref trio/push_dma/app.c for an example of how to use push DMA. - * - * @section trio_shortcomings Plans for Future API Revisions - * - * The simulation framework is incomplete. Future features include: - * - * - Support for reset and deallocation of resources. - * - * - Support for pull DMA. - * - * - Support for interrupt regions and user-space interrupt delivery. - * - * - Support for getting BAR mappings and reserving regions of BAR - * address space. - */ -#ifndef _GXIO_TRIO_H_ -#define _GXIO_TRIO_H_ - -#include <linux/types.h> - -#include <gxio/common.h> -#include <gxio/dma_queue.h> - -#include <arch/trio_constants.h> -#include <arch/trio.h> -#include <arch/trio_pcie_intfc.h> -#include <arch/trio_pcie_rc.h> -#include <arch/trio_shm.h> -#include <hv/drv_trio_intf.h> -#include <hv/iorpc.h> - -/* A context object used to manage TRIO hardware resources. */ -typedef struct { - - /* File descriptor for calling up to Linux (and thus the HV). */ - int fd; - - /* The VA at which the MAC MMIO registers are mapped. */ - char *mmio_base_mac; - - /* The VA at which the PIO config space are mapped for each PCIe MAC. - Gx36 has max 3 PCIe MACs per TRIO shim. */ - char *mmio_base_pio_cfg[TILEGX_TRIO_PCIES]; - -#ifdef USE_SHARED_PCIE_CONFIG_REGION - /* Index of the shared PIO region for PCI config access. */ - int pio_cfg_index; -#else - /* Index of the PIO region for PCI config access per MAC. */ - int pio_cfg_index[TILEGX_TRIO_PCIES]; -#endif - - /* The VA at which the push DMA MMIO registers are mapped. */ - char *mmio_push_dma[TRIO_NUM_PUSH_DMA_RINGS]; - - /* The VA at which the pull DMA MMIO registers are mapped. */ - char *mmio_pull_dma[TRIO_NUM_PUSH_DMA_RINGS]; - - /* Application space ID. */ - unsigned int asid; - -} gxio_trio_context_t; - -/* Command descriptor for push or pull DMA. */ -typedef TRIO_DMA_DESC_t gxio_trio_dma_desc_t; - -/* A convenient, thread-safe interface to an eDMA ring. */ -typedef struct { - - /* State object for tracking head and tail pointers. */ - __gxio_dma_queue_t dma_queue; - - /* The ring entries. */ - gxio_trio_dma_desc_t *dma_descs; - - /* The number of entries minus one. */ - unsigned long mask_num_entries; - - /* The log2() of the number of entries. */ - unsigned int log2_num_entries; - -} gxio_trio_dma_queue_t; - -/* Initialize a TRIO context. - * - * This function allocates a TRIO "service domain" and maps the MMIO - * registers into the the caller's VA space. - * - * @param trio_index Which TRIO shim; Gx36 must pass 0. - * @param context Context object to be initialized. - */ -extern int gxio_trio_init(gxio_trio_context_t *context, - unsigned int trio_index); - -/* This indicates that an ASID hasn't been allocated. */ -#define GXIO_ASID_NULL -1 - -/* Ordering modes for map memory regions and scatter queue regions. */ -typedef enum gxio_trio_order_mode_e { - /* Writes are not ordered. Reads always wait for previous writes. */ - GXIO_TRIO_ORDER_MODE_UNORDERED = - TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_UNORDERED, - /* Both writes and reads wait for previous transactions to complete. */ - GXIO_TRIO_ORDER_MODE_STRICT = - TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_STRICT, - /* Writes are ordered unless the incoming packet has the - relaxed-ordering attributes set. */ - GXIO_TRIO_ORDER_MODE_OBEY_PACKET = - TRIO_MAP_MEM_SETUP__ORDER_MODE_VAL_REL_ORD -} gxio_trio_order_mode_t; - -/* Initialize a memory mapping region. - * - * @param context An initialized TRIO context. - * @param map A Memory map region allocated by gxio_trio_alloc_memory_map(). - * @param target_mem VA of backing memory, should be registered via - * gxio_trio_register_page() and aligned to 4kB. - * @param target_size Length of the memory mapping, must be a multiple - * of 4kB. - * @param asid ASID to be used for Tile-side address translation. - * @param mac MAC number. - * @param bus_address Bus address at which the mapping starts. - * @param order_mode Memory ordering mode for this mapping. - * @return Zero on success, else ::GXIO_TRIO_ERR_BAD_MEMORY_MAP, - * GXIO_TRIO_ERR_BAD_ASID, or ::GXIO_TRIO_ERR_BAD_BUS_RANGE. - */ -extern int gxio_trio_init_memory_map(gxio_trio_context_t *context, - unsigned int map, void *target_mem, - size_t target_size, unsigned int asid, - unsigned int mac, uint64_t bus_address, - gxio_trio_order_mode_t order_mode); - -/* Flags that can be passed to resource allocation functions. */ -enum gxio_trio_alloc_flags_e { - GXIO_TRIO_ALLOC_FIXED = HV_TRIO_ALLOC_FIXED, -}; - -/* Flags that can be passed to memory registration functions. */ -enum gxio_trio_mem_flags_e { - /* Do not fill L3 when writing, and invalidate lines upon egress. */ - GXIO_TRIO_MEM_FLAG_NT_HINT = IORPC_MEM_BUFFER_FLAG_NT_HINT, - - /* L3 cache fills should only populate IO cache ways. */ - GXIO_TRIO_MEM_FLAG_IO_PIN = IORPC_MEM_BUFFER_FLAG_IO_PIN, -}; - -/* Flag indicating a request generator uses a special traffic - class. */ -#define GXIO_TRIO_FLAG_TRAFFIC_CLASS(N) HV_TRIO_FLAG_TC(N) - -/* Flag indicating a request generator uses a virtual function - number. */ -#define GXIO_TRIO_FLAG_VFUNC(N) HV_TRIO_FLAG_VFUNC(N) - -/***************************************************************** - * Memory Registration * - ******************************************************************/ - -/* Allocate Application Space Identifiers (ASIDs). Each ASID can - * register up to 16 page translations. ASIDs are used by memory map - * regions, scatter queues, and DMA queues to translate application - * VAs into memory system PAs. - * - * @param context An initialized TRIO context. - * @param count Number of ASIDs required. - * @param first Index of first ASID if ::GXIO_TRIO_ALLOC_FIXED flag - * is set, otherwise ignored. - * @param flags Flag bits, including bits from ::gxio_trio_alloc_flags_e. - * @return Index of first ASID, or ::GXIO_TRIO_ERR_NO_ASID if allocation - * failed. - */ -extern int gxio_trio_alloc_asids(gxio_trio_context_t *context, - unsigned int count, unsigned int first, - unsigned int flags); - -#endif /* ! _GXIO_TRIO_H_ */ |