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