From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Google-Smtp-Source: AH8x226gqF+zC9H83frzwb7JWyPn61p3+HLnsCkSerazcqbwMXs5ZmSKTmBmOOcrSrf5hjCarMg3 ARC-Seal: i=1; a=rsa-sha256; t=1516707132; cv=none; d=google.com; s=arc-20160816; b=ywtolwLctHI6zZx3YecsThdm6C0p24JvD546LF8+9pduoRjaAeeFdBVt3SWZrTdTbX Y6fOrh+TYN2c81UMOVQJ3734bDO1Lsf5uNMrgLbCVvnjnh0v96rDUxbUQ3aJAiMBe3A7 ZOUouHiqGBO/S0qthuGRqwgsy099sZMgeZu8c/mR/tH5tTRJg4Wz0aDive/kWVSSmBf2 3Up9HwbF2GWjJ3rULrYdhWDh2VViJb7ChnL9Oia6UK4NiRerwPLpFPvHf3rZEH6znr+G KijJZFxBrjgA1jHERaFI5kn8xrhziabj1LqVvlpifWCdjdMAV6gpBa7rsZ0WEVNcDZYP IJZw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=message-id:references:in-reply-to:date:subject:cc:to:from :arc-authentication-results; bh=umCfXQVOsY8SeWcrSMO4+dfkH0M7bo1u5uEx9Sqd5ms=; b=vxQfqFG3JNyp/M6tl3dLMaVYytI5uBeckKAjNmwDjsEn8te7SWa166IlrL0H6++pIA U3mbN7m2NJNEDAq3UdjKG40F11/IzXAu/zhGb1x9H1ZzdpbWyUOooT+PZGGh+nphj3vy sLQLPTj9xtzYoMrn6/oAg2gDDu1zznuEVdvdiFUG3ssN7tIHbFEkS4WPUlFYM9NS5Zz6 8t5hpyjdXyH/sp9pJ0kPFfpHpbEa07cXaP+0z3k36TL6mLTd3w9yazHRavtD96YovGUU C6aqxeSM/VyH2Un+PXJgMj69Vl+xrakdC+tKZ8jxZiF7xnNSZQQbJkMNtozhjtiCZavW yKVg== ARC-Authentication-Results: i=1; mx.google.com; spf=neutral (google.com: 148.163.156.1 is neither permitted nor denied by best guess record for domain of fbarrat@linux.vnet.ibm.com) smtp.mailfrom=fbarrat@linux.vnet.ibm.com; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=ibm.com Authentication-Results: mx.google.com; spf=neutral (google.com: 148.163.156.1 is neither permitted nor denied by best guess record for domain of fbarrat@linux.vnet.ibm.com) smtp.mailfrom=fbarrat@linux.vnet.ibm.com; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=ibm.com From: Frederic Barrat To: linuxppc-dev@lists.ozlabs.org, linux-kernel@vger.kernel.org Cc: arnd@arndb.de, gregkh@linuxfoundation.org, mpe@ellerman.id.au, andrew.donnellan@au1.ibm.com, alastair@au1.ibm.com Subject: [PATCH v2 12/13] ocxl: Documentation Date: Tue, 23 Jan 2018 12:31:47 +0100 X-Mailer: git-send-email 2.14.1 In-Reply-To: <20180123113148.6024-1-fbarrat@linux.vnet.ibm.com> References: <20180123113148.6024-1-fbarrat@linux.vnet.ibm.com> X-TM-AS-GCONF: 00 x-cbid: 18012311-0008-0000-0000-000004C4DF35 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 18012311-0009-0000-0000-00001E585EBC Message-Id: <20180123113148.6024-13-fbarrat@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2018-01-23_03:,, signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=2 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1709140000 definitions=main-1801230158 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: =?utf-8?q?1590382698519147689?= X-GMAIL-MSGID: =?utf-8?q?1590382698519147689?= X-Mailing-List: linux-kernel@vger.kernel.org List-ID: ocxl.rst gives a quick, high-level view of opencapi. Update ioctl-number.txt to reflect ioctl numbers being used by the ocxl driver Signed-off-by: Frederic Barrat --- Documentation/ABI/testing/sysfs-class-ocxl | 35 +++++++ Documentation/accelerators/ocxl.rst | 160 +++++++++++++++++++++++++++++ Documentation/ioctl/ioctl-number.txt | 1 + 3 files changed, 196 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-ocxl create mode 100644 Documentation/accelerators/ocxl.rst diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl new file mode 100644 index 000000000000..ac11deb71235 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -0,0 +1,35 @@ +What: /sys/class/ocxl//afu_version +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Version of the AFU, in the format : + Reflects what is read in the configuration space of the AFU + +What: /sys/class/ocxl//contexts +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Number of contexts for the AFU, in the format / + where: + n: number of currently active contexts, for debug + max: maximum number of contexts supported by the AFU + +What: /sys/class/ocxl//pp_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the per-process mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl//global_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the global mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl//global_mmio_area +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Give access the global mmio area for the AFU diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst new file mode 100644 index 000000000000..4f7af841d935 --- /dev/null +++ b/Documentation/accelerators/ocxl.rst @@ -0,0 +1,160 @@ +======================================================== +OpenCAPI (Open Coherent Accelerator Processor Interface) +======================================================== + +OpenCAPI is an interface between processors and accelerators. It aims +at being low-latency and high-bandwidth. The specification is +developed by the `OpenCAPI Consortium `_. + +It allows an accelerator (which could be a FPGA, ASICs, ...) to access +the host memory coherently, using virtual addresses. An OpenCAPI +device can also host its own memory, that can be accessed from the +host. + +OpenCAPI is known in linux as 'ocxl', as the open, processor-agnostic +evolution of 'cxl' (the driver for the IBM CAPI interface for +powerpc), which was named that way to avoid confusion with the ISDN +CAPI subsystem. + + +High-level view +=============== + +OpenCAPI defines a Data Link Layer (DL) and Transaction Layer (TL), to +be implemented on top of a physical link. Any processor or device +implementing the DL and TL can start sharing memory. + +:: + + +-----------+ +-------------+ + | | | | + | | | Accelerated | + | Processor | | Function | + | | +--------+ | Unit | +--------+ + | |--| Memory | | (AFU) |--| Memory | + | | +--------+ | | +--------+ + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | TL | | TLX | + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | DL | | DLX | + +-----------+ +-------------+ + | | + | PHY | + +---------------------------------------+ + + + +Device discovery +================ + +OpenCAPI relies on a PCI-like configuration space, implemented on the +device. So the host can discover AFUs by querying the config space. + +OpenCAPI devices in Linux are treated like PCI devices (with a few +caveats). The firmware is expected to abstract the hardware as if it +was a PCI link. A lot of the existing PCI infrastructure is reused: +devices are scanned and BARs are assigned during the standard PCI +enumeration. Commands like 'lspci' can therefore be used to see what +devices are available. + +The configuration space defines the AFU(s) that can be found on the +physical adapter, such as its name, how many memory contexts it can +work with, the size of its MMIO areas, ... + + + +MMIO +==== + +OpenCAPI defines two MMIO areas for each AFU: + +* the global MMIO area, with registers pertinent to the whole AFU. +* a per-process MMIO area, which has a fixed size for each context. + + + +AFU interrupts +============== + +OpenCAPI includes the possibility for an AFU to send an interrupt to a +host process. It is done through a 'intrp_req' defined in the +Transaction Layer, specifying a 64-bit object handle which defines the +interrupt. + +The driver allows a process to allocate an interrupt and obtain its +64-bit object handle, that can be passed to the AFU. + + + +char devices +============ + +The driver creates one char device per AFU found on the physical +device. A physical device may have multiple functions and each +function can have multiple AFUs. At the time of this writing though, +it has only been tested with devices exporting only one AFU. + +Char devices can be found in /dev/ocxl/ and are named as: +/dev/ocxl/.. + +where is a max 20-character long name, as found in the +config space of the AFU. + is added by the driver and can help distinguish devices +when a system has more than one instance of the same OpenCAPI device. + is also to help distinguish AFUs in the unlikely case where a +device carries multiple copies of the same AFU. + + + +Sysfs class +=========== + +An ocxl class is added for the devices representing the AFUs. See +/sys/class/ocxl. The layout is described in +Documentation/ABI/testing/sysfs-class-ocxl + + + +User API +======== + +open +---- + +Based on the AFU definition found in the config space, an AFU may +support working with more than one memory context, in which case the +associated char device may be opened multiple times by different +processes. + + +ioctl +----- + +OCXL_IOCTL_ATTACH: + + Attach the memory context of the calling process to the AFU so that + the AFU can access its memory. + +OCXL_IOCTL_IRQ_ALLOC: + + Allocate an AFU interrupt and return an identifier. + +OCXL_IOCTL_IRQ_FREE: + + Free a previously allocated AFU interrupt. + +OCXL_IOCTL_IRQ_SET_FD: + + Associate an event fd to an AFU interrupt so that the user process + can be notified when the AFU sends an interrupt. + + +mmap +---- + +A process can mmap the per-process MMIO area for interactions with the +AFU. diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 3e3fdae5f3ed..6501389d55b9 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -326,6 +326,7 @@ Code Seq#(hex) Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h 0xCA 80-BF uapi/scsi/cxlflash_ioctl.h 0xCB 00-1F CBM serial IEC bus in development: -- 2.14.1