299 lines
12 KiB
C
299 lines
12 KiB
C
/*
|
|
* 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_ */
|