path: root/Documentation/sparc/oradax/dax-hv-api.txt

Excerpt from UltraSPARC Virtual Machine Specification
Compiled from version 3.0.20+15
Publication date 2017-09-25 08:21
Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved.
Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf"
Authors:
	 Charles Kunzman
	 Sam Glidden
	 Mark Cianchetti


Chapter 36. Coprocessor services
        The following APIs provide access via the Hypervisor to hardware assisted data processing functionality.
        These APIs may only be provided by certain platforms, and may not be available to all virtual machines
        even on supported platforms. Restrictions on the use of these APIs may be imposed in order to support
        live-migration and other system management activities.

36.1. Data Analytics Accelerator
        The Data Analytics Accelerator (DAX) functionality is a collection of hardware coprocessors that provide
        high speed processoring of database-centric operations. The coprocessors may support one or more of
        the following data query operations: search, extraction, compression, decompression, and translation. The
        functionality offered may vary by virtual machine implementation.

        The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device
        compatibilty property. Functionality is accessed through the submission of Command Control Blocks
        (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status
        of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a
        separate Completion Area and, unless execution order is specifically restricted through the use of serial-
        conditional flags, the execution order of submitted CCBs is arbitrary. Likewise, the time to completion
        for a given CCB is never guaranteed.

        Guest software may implement a software timeout on CCB operations, and if the timeout is exceeded, the
        operation may be cancelled or killed via the ccb_kill API function. It is recommended for guest software
        to implement a software timeout to account for certain RAS errors which may result in lost CCBs. It is
        recommended such implementation use the ccb_info API function to check the status of a CCB prior to
        killing it in order to determine if the CCB is still in queue, or may have been lost due to a RAS error.

        There is no fixed limit on the number of outstanding CCBs guest software may have queued in the virtual
        machine, however, internal resource limitations within the virtual machine can cause CCB submissions
        to be temporarily rejected with EWOULDBLOCK. In such cases, guests should continue to attempt
        submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would
        not be a guarantee that a future submission would succeed.

        The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual
        device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device
        node”).

36.1.1. DAX Compatibility Property
        The query functionality may vary based on the compatibility property of the virtual device:

36.1.1.1. "ORCL,sun4v-dax" Device Compatibility
        Available CCB commands:

        • No-op/Sync

        • Extract

        • Scan Value

        • Inverted Scan Value

        • Scan Range


                                                     509
                                             Coprocessor services


        • Inverted Scan Range

        • Translate

        • Inverted Translate

        • Select

        See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.

        Only version 0 CCBs are available.

36.1.1.2. "ORCL,sun4v-dax-fc" Device Compatibility
        "ORCL,sun4v-dax-fc" is compatible with the "ORCL,sun4v-dax" interface, and includes additional CCB
        bit fields and controls.

36.1.1.3. "ORCL,sun4v-dax2" Device Compatibility
        Available CCB commands:

        • No-op/Sync

        • Extract

        • Scan Value

        • Inverted Scan Value

        • Scan Range

        • Inverted Scan Range

        • Translate

        • Inverted Translate

        • Select

        See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.

        Version 0 and 1 CCBs are available. Only version 0 CCBs may use Huffman encoded data, whereas only
        version 1 CCBs may use OZIP.

36.1.2. DAX Virtual Device Interrupts
        The DAX virtual device has multiple interrupts associated with it which may be used by the guest if
        desired. The number of device interrupts available to the guest is indicated in the virtual device node of the
        guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). If the device
        node indicates N interrupts available, the guest may use any value from 0 to N - 1 (inclusive) in a CCB
        interrupt number field. Using values outside this range will result in the CCB being rejected for an invalid
        field value.

        The interrupts may be bound and managed using the standard sun4v device interrupts API (Chapter 16,
        Device interrupt services). Sysino interrupts are not available for DAX devices.

36.2. Coprocessor Control Block (CCB)
        CCBs are either 64 or 128 bytes long, depending on the operation type. The exact contents of the CCB
        are command specific, but all CCBs contain at least one memory buffer address. All memory locations


                                                      510
                                    Coprocessor services


referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed
via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not
guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB
execution.

All CCBs begin with a common 32-bit header.

Table 36.1. CCB Header Format
Bits          Field Description
[31:28]       CCB version. For API version 2.0: set to 1 if CCB uses OZIP encoding; set to 0 if the CCB
              uses Huffman encoding; otherwise either 0 or 1. For API version 1.0: always set to 0.
[27]          When API version 2.0 is negotiated, this is the Pipeline Flag [512]. It is reserved in
              API version 1.0