You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
298 lines
12 KiB
298 lines
12 KiB
/* |
|
* 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_ */
|
|
|