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
[26]          Long CCB flag [512]
[25]          Conditional synchronization flag [512]
[24]          Serial synchronization flag
[23:16]       CCB operation code:
               0x00        No Operation (No-op) or Sync
               0x01        Extract
               0x02        Scan Value
               0x12        Inverted Scan Value
               0x03        Scan Range
               0x13        Inverted Scan Range
               0x04        Translate
               0x14        Inverted Translate
               0x05        Select
[15:13]       Reserved
[12:11]       Table address type
               0b'00       No address
               0b'01       Alternate context virtual address
               0b'10       Real address
               0b'11       Primary context virtual address
[10:8]        Output/Destination address type
               0b'000      No address
               0b'001      Alternate context virtual address
               0b'010      Real address
               0b'011      Primary context virtual address
               0b'100      Reserved
               0b'101      Reserved
               0b'110      Reserved
               0b'111      Reserved
[7:5]         Secondary source address type


                                            511
                                    Coprocessor services


Bits           Field Description
                0b'000       No address
                0b'001       Alternate context virtual address
                0b'010       Real address
                0b'011       Primary context virtual address
                0b'100       Reserved
                0b'101       Reserved
                0b'110       Reserved
                0b'111       Reserved
[4:2]          Primary source address type
                0b'000       No address
                0b'001       Alternate context virtual address
                0b'010       Real address
                0b'011       Primary context virtual address
                0b'100       Reserved
                0b'101       Reserved
                0b'110       Reserved
                0b'111       Reserved
[1:0]          Completion area address type
                0b'00        No address
                0b'01        Alternate context virtual address
                0b'10        Real address
                0b'11        Primary context virtual address

The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes
and 1 for 128 bytes.

The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial
flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same
CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs
with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the
previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs
to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag.
A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional
and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs
execute in parallel based on the completion of another CCB.

The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to
the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from
memory. The Pipeline flag is advisory and may be dropped.

Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the
target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs
is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB
with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional
bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit.


                                             512
                                               Coprocessor services


          The input of the target CCB must start within 64 bytes of the output of the source CCB or the pipeline flag
          will be ignored. All CCBs in a pipeline must be submitted in the same call to ccb_submit.

          The various address type fields indicate how the various address values used in the CCB should be
          interpreted by the virtual machine. Not all of the types specified are used by every CCB format. Types
          which are not applicable to the given CCB command should be indicated as type 0 (No address). Virtual
          addresses used in the CCB must have translation entries present in either the TLB or a configured TSB
          for the submitting virtual processor. Virtual addresses which cannot be translated by the virtual machine
          will result in the CCB submission being rejected, with the causal virtual address indicated. The CCB
          may be resubmitted after inserting the translation, or the address may be translated by guest software and
          resubmitted using the real address translation.

36.2.1. Query CCB Command Formats
36.2.1.1. Supported Data Formats, Elements Sizes and Offsets
          Data for query commands may be encoded in multiple possible formats. The data query commands use a
          common set of values to indicate the encoding formats of the data being processed. Some encoding formats
          require multiple data streams for processing, requiring the specification of both primary data formats (the
          encoded data) and secondary data streams (meta-data for the encoded data).

36.2.1.1.1. Primary Input Format

          The primary input format code is a 4-bit field when it is used. There are 10 primary input formats available.
          The packed formats are not endian neutral. Code values not listed below are reserved.

          Code        Format                              Description
          0x0         Fixed width byte packed             Up to 16 bytes
          0x1         Fixed width bit packed              Up to 15 bits (CCB version 0) or 23 bits (CCB version
                                                          1); bits are read most significant bit to least significant bit
                                                          within a byte
          0x2         Variable width byte packed          Data stream of lengths must be provided as a secondary
                                                          input
          0x4         Fixed width byte packed with run Up to 16 bytes; data stream of run lengths must be
                      length encoding                  provided as a secondary input
          0x5         Fixed width bit packed with run Up to 15 bits (CCB version 0) or 23 bits (CCB version
                      length encoding                 1); bits are read most significant bit to least significant bit
                                                      within a byte; data stream of run lengths must be provided
                                                      as a secondary input
          0x8         Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream
                      Huffman (CCB version 0) or bits are read most significant bit to least significant bit
                      OZIP (CCB version 1) encoding within a byte; pointer to the encoding table must be
                                                    provided
          0x9         Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits (CCB version
                      Huffman (CCB version 0) or 1); compressed stream bits are read most significant bit to
                      OZIP (CCB version 1) encoding least significant bit within a byte; pointer to the encoding
                                                    table must be provided
          0xA         Variable width byte packed with Up to 16 bytes before the encoding; compressed stream
                      Huffman (CCB version 0) or bits are read most significant bit to least significant bit
                      OZIP (CCB version 1) encoding within a byte; data stream of lengths must be provided as
                                                      a secondary input; pointer to the encoding table must be
                                                      provided


                                                        513
                                               Coprocessor services


          Code        Format                              Description
          0xC         Fixed width byte packed with        Up to 16 bytes before the encoding; compressed stream
                      run length encoding, followed by    bits are read most significant bit to least significant bit
                      Huffman (CCB version 0) or          within a byte; data stream of run lengths must be provided
                      OZIP (CCB version 1) encoding       as a secondary input; pointer to the encoding table must
                                                          be provided
          0xD         Fixed width bit packed with         Up to 15 bits (CCB version 0) or 23 bits(CCB version 1)
                      run length encoding, followed by    before the encoding; compressed stream bits are read most
                      Huffman (CCB version 0) or          significant bit to least significant bit within a byte; data
                      OZIP (CCB version 1) encoding       stream of run lengths must be provided as a secondary
                                                          input; pointer to the encoding table must be provided

          If OZIP encoding is used, there must be no reserved bytes in the table.

36.2.1.1.2. Primary Input Element Size

          For primary input data streams with fixed size elements, the element size must be indicated in the CCB
          command. The size is encoded as the number of bits or bytes, minus one. The valid value range for this
          field depends on the input format selected, as listed in the table above.

36.2.1.1.3. Secondary Input Format

          For primary input data streams which require a secondary input stream, the secondary input stream is
          always encoded in a fixed width, bit-packed format. The bits are read from most significant bit to least
          significant bit within a byte. There are two encoding options for the secondary input stream data elements,
          depending on whether the value of 0 is needed:

          Secondary           Input Description
          Format Code
          0                          Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes
                                     to 2, etc)
          1                          Element is stored as value

36.2.1.1.4. Secondary Input Element Size

          Secondary input element size is encoded as a two bit field:

          Secondary Input Size Description
          Code
          0x0                        1 bit
          0x1                        2 bits
          0x2                        4 bits
          0x3                        8 bits

36.2.1.1.5. Input Element Offsets

          Bit-wise input data streams may have any alignment within the base addressed byte. The offset, specified
          from most significant bit to least significant bit, is provided as a fixed 3 bit field for each input type. A
          value of 0 indicates that the first input element begins at the most significant bit in the first byte, and a
          value of 7 indicates it begins with the least significant bit.

          This field should be zero for any byte-wise primary input data streams.


                                                        514
                                              Coprocessor services


36.2.1.1.6. Output Format

          Query commands support multiple sizes and encodings for output data streams. There are four possible
          output encodings, and up to four supported element sizes per encoding. Not all output encodings are
          supported for every command. The format is indicated by a 4-bit field in the CCB:

           Output Format Code        Description
           0x0                       Byte aligned, 1 byte elements
           0x1                       Byte aligned, 2 byte elements
           0x2                       Byte aligned, 4 byte elements
           0x3                       Byte aligned, 8 byte elements
           0x4                       16 byte aligned, 16 byte elements
           0x5                       Reserved
           0x6                       Reserved
           0x7                       Reserved
           0x8                       Packed vector of single bit elements
           0x9                       Reserved
           0xA                       Reserved
           0xB                       Reserved
           0xC                       Reserved
           0xD                       2 byte elements where each element is the index value of a bit,
                                     from an bit vector, which was 1.
           0xE                       4 byte elements where each element is the index value of a bit,
                                     from an bit vector, which was 1.
           0xF                       Reserved

36.2.1.1.7. Application Data Integrity (ADI)

          On platforms which support ADI, the ADI version number may be specified for each separate memory
          access type used in the CCB command. ADI checking only occurs when reading data. When writing data,
          the specified ADI version number overwrites any existing ADI value in memory.

          An ADI version value of 0 or 0xF indicates the ADI checking is disabled for that data access, even if it is
          enabled in memory. By setting the appropriate flag in CCB_SUBMIT (Section 36.3.1, “ccb_submit”) it is
          also an option to disable ADI checking for all inputs accessed via virtual address for all CCBs submitted
          during that hypercall invocation.

          The ADI value is only guaranteed to be checked on the first 64 bytes of each data access. Mismatches on
          subsequent data chunks may not be detected, so guest software should be careful to use page size checking
          to protect against buffer overruns.

36.2.1.1.8. Page size checking

          All data accesses used in CCB commands must be bounded within a single memory page. When addresses
          are provided using a virtual address, the page size for checking is extracted from the TTE for that virtual
          address. When using real addresses, the guest must supply the page size in the same field as the address
          value. The page size must be one of the sizes supported by the underlying virtual machine. Using a value
          that is not supported may result in the CCB submission being rejected or the generation of a CCB parsing
          error in the completion area.


                                                       515
                                               Coprocessor services


36.2.1.2. Extract command

        Converts an input vector in one format to an output vector in another format. All input format types are
        supported.

        The only supported output format is a padded, byte-aligned output stream, using output codes 0x0 - 0x4.
        When the specified output element size is larger than the extracted input element size, zeros are padded to
        the extracted input element. First, if the decompressed input size is not a whole number of bytes, 0 bits are
        padded to the most significant bit side till the next byte boundary. Next, if the output element size is larger
        than the byte padded input element, bytes of value 0 are added based on the Padding Direction bit in the
        CCB. If the output element size is smaller than the byte-padded input element size, the input element is
        truncated by dropped from the least significant byte side until the selected output size is reached.

        The return value of the CCB completion area is invalid. The “number of elements processed” field in the
        CCB completion area will be valid.

        The extract CCB is a 64-byte “short format” CCB.

        The extract CCB command format can be specified by the following packed C structure for a big-endian
        machine:


                  struct extract_ccb {
                         uint32_t header;
                         uint32_t control;
                         uint64_t completion;
                         uint64_t primary_input;
                         uint64_t data_access_control;
                         uint64_t secondary_input;
                         uint64_t reserved;
                         uint64_t output;
                         uint64_t table;
                  };


        The exact field offsets, sizes, and composition are as follows:

         Offset         Size            Field Description
         0              4               CCB header (Table 36.1, “CCB Header Format”)
         4              4               Command control
                                        Bits        Field Description
                                        [31:28]     Primary Input Format (see Section 36.2.1.1.1, “Primary Input
                                                    Format”)
                                        [27:23]     Primary Input Element Size (see Section 36.2.1.1.2, “Primary
                                                    Input Element Size”)
                                        [22:20]     Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                                    Element Offsets”)
                                        [19]        Secondary Input Format (see Section 36.2.1.1.3, “Secondary
                                                    Input Format”)
                                        [18:16]     Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                                    Element Offsets”)


                                                       516
                        Coprocessor services


Offset   Size   Field Description
                Bits         Field Description
                [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
                             “Secondary Input Element Size”
                [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
                [9]          Padding Direction selector: A value of 1 causes padding bytes
                             to be added to the left side of output elements. A value of 0
                             causes padding bytes to be added to the right side of output
                             elements.
                [8:0]        Reserved
8        8      Completion
                Bits         Field Description
                [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
                             Integrity (ADI)”)
                [59]         If set to 1, a virtual device interrupt will be generated using
                             the device interrupt number specified in the lower bits of this
                             completion word. If 0, the lower bits of this completion word
                             are ignored.
                [58:6]       Completion area address bits [58:6]. Address type is
                             determined by CCB header.
                [5:0]        Virtual device interrupt number for completion interrupt, if
                             enabled.
16       8      Primary Input
                Bits         Field Description
                [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
                             Integrity (ADI)”)
                [59:56]      If using real address, these bits should be filled in with the
                             page size code for the page boundary checking the guest wants
                             the virtual machine to use when accessing this data stream
                             (checking is only guaranteed to be performed when using API
                             version 1.1 and later). If using a virtual address, this field will
                             be used as as primary input address bits [59:56].
                [55:0]       Primary input address bits [55:0]. Address type is determined
                             by CCB header.
24       8      Data Access Control
                Bits         Field Description
                [63:62]      Flow Control
                             Value      Description
                             0b'00      Disable flow control
                             0b'01      Enable flow control (only valid with "ORCL,sun4v-
                                        dax-fc" compatible virtual device variants)
                             0b'10      Reserved
                             0b'11      Reserved
                [61:60]      Reserved (API 1.0)


                                517
                       Coprocessor services


Offset   Size   Field Description
                Bits        Field Description
                            Pipeline target (API 2.0)
                            Value      Description
                            0b'00      Connect to primary input
                            0b'01      Connect to secondary input
                            0b'10      Reserved
                            0b'11      Reserved
                [59:40]     Output buffer size given in units of 64 bytes, minus 1. Value of
                            0 means 64 bytes, value of 1 means 128 bytes, etc. Buffer size is
                            only enforced if flow control is enabled in Flow Control field.
                [39:32]     Reserved
                [31:30]     Output Data Cache Allocation
                            Value      Description
                            0b'00      Do not allocate cache lines for output data stream.
                            0b'01      Force cache lines for output data stream to be
                                       allocated in the cache that is local to the submitting
                                       virtual cpu.
                            0b'10      Allocate cache lines for output data stream, but allow
                                       existing cache lines associated with the data to remain
                                       in their current cache instance. Any memory not
                                       already in cache will be allocated in the cache local
                                       to the submitting virtual cpu.
                            0b'11      Reserved
                [29:26]     Reserved
                [25:24]     Primary Input Length Format
                            Value      Description
                            0b'00      Number of primary symbols
                            0b'01      Number of primary bytes
                            0b'10      Number of primary bits
                            0b'11      Reserved
                [23:0]      Primary Input Length
                            Format                      Field Value
                            # of primary symbols        Number of input elements to process,
                                                        minus 1. Command execution stops
                                                        once count is reached.
                            # of primary bytes          Number of input bytes to process,
                                                        minus 1. Command execution stops
                                                        once count is reached. The count is
                                                        done before any decompression or
                                                        decoding.
                            # of primary bits           Number of input bits to process,
                                                        minus 1. Command execution stops



                               518
                                                Coprocessor services


        Offset          Size           Field Description
                                        Bits         Field Description
                                                     Format                     Field Value
                                                                                once count is reached. The count is
                                                                                done before any decompression or
                                                                                decoding, and does not include any
                                                                                bits skipped by the Primary Input
                                                                                Offset field value of the command
                                                                                control word.
        32              8              Secondary Input, if used by Primary Input Format. Same fields as Primary
                                       Input.
        40              8              Reserved
        48              8              Output (same fields as Primary Input)
        56              8              Symbol Table (if used by Primary Input)
                                        Bits         Field Description
                                        [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
                                                     Integrity (ADI)”)
                                        [59:56]      If using real address, these bits should be filled in with the
                                                     page size code for the page boundary checking the guest wants
                                                     the virtual machine to use when accessing this data stream
                                                     (checking is only guaranteed to be performed when using API
                                                     version 1.1 and later). If using a virtual address, this field will
                                                     be used as as symbol table address bits [59:56].
                                        [55:4]       Symbol table address bits [55:4]. Address type is determined
                                                     by CCB header.
                                        [3:0]        Symbol table version
                                                     Value     Description
                                                     0         Huffman encoding. Must use 64 byte aligned table
                                                               address. (Only available when using version 0 CCBs)
                                                     1         OZIP encoding. Must use 16 byte aligned table
                                                               address. (Only available when using version 1 CCBs)


36.2.1.3. Scan commands

        The scan commands search a stream of input data elements for values which match the selection criteria.
        All the input format types are supported. There are multiple formats for the scan commands, allowing the
        scan to search for exact matches to one value, exact matches to either of two values, or any value within
        a specified range. The specific type of scan is indicated by the command code in the CCB header. For the
        scan range commands, the boundary conditions can be specified as greater-than-or-equal-to a value, less-
        than-or-equal-to a value, or both by using two boundary values.

        There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
        0xD, and 0xE). For the standard scan command using the bit vector output, for each input element there
        exists one bit in the vector that is set if the input element matched the scan criteria, or clear if not. The
        inverted scan command inverts the polarity of the bits in the output. The most significant bit of the first
        byte of the output stream corresponds to the first element in the input stream. The standard index array
        output format contains one array entry for each input element that matched the scan criteria. Each array



                                                         519
                                       Coprocessor services


entry is the index of an input element that matched the scan criteria. An inverted scan command produces
a similar array, but of all the input elements which did NOT match the scan criteria.

The return value of the CCB completion area contains the number of input elements found which match
the scan criteria (or number that did not match for the inverted scans). The “number of elements processed”
field in the CCB completion area will be valid, indicating the number of input elements processed.

These commands are 128-byte “long format” CCBs.

The scan CCB command format can be specified by the following packed C structure for a big-endian
machine:


         struct scan_ccb         {
                uint32_t         header;
                uint32_t         control;
                uint64_t         completion;
                uint64_t         primary_input;
                uint64_t         data_access_control;
                uint64_t         secondary_input;
                uint64_t         match_criteria0;
                uint64_t         output;
                uint64_t         table;
                uint64_t         match_criteria1;
                uint64_t         match_criteria2;
                uint64_t         match_criteria3;
                uint64_t         reserved[5];
         };


The exact field offsets, sizes, and composition are as follows:

Offset         Size            Field Description
0              4               CCB header (Table 36.1, “CCB Header Format”)
4              4               Command control
                               Bits         Field Description
                               [31:28]      Primary Input Format (see Section 36.2.1.1.1, “Primary Input
                                            Format”)
                               [27:23]      Primary Input Element Size (see Section 36.2.1.1.2, “Primary
                                            Input Element Size”)
                               [22:20]      Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                            Element Offsets”)
                               [19]         Secondary Input Format (see Section 36.2.1.1.3, “Secondary
                                            Input Format”)
                               [18:16]      Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                            Element Offsets”)
                               [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
                                            “Secondary Input Element Size”
                               [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
                               [9:5]        Operand size for first scan criteria value. In a scan value
                                            operation, this is one of two potential extact match values.
                                            In a scan range operation, this is the size of the upper range


                                               520
                        Coprocessor services


Offset   Size   Field Description
                Bits         Field Description
                             boundary. The value of this field is the number of bytes in the
                             operand, minus 1. Values 0xF-0x1E are reserved. A value of
                             0x1F indicates this operand is not in use for this scan operation.
                [4:0]        Operand size for second scan criteria value. In a scan value
                             operation, this is one of two potential extact match values.
                             In a scan range operation, this is the size of the lower range
                             boundary. The value of this field is the number of bytes in the
                             operand, minus 1. Values 0xF-0x1E are reserved. A value of
                             0x1F indicates this operand is not in use for this scan operation.
8        8      Completion (same fields as Section 36.2.1.2, “Extract command”)
16       8      Primary Input (same fields as Section 36.2.1.2, “Extract command”)
24       8      Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
32       8      Secondary Input, if used by Primary Input Format. Same fields as Primary
                Input.
40       4      Most significant 4 bytes of first scan criteria operand. If first operand is less
                than 4 bytes, the value is left-aligned to the lowest address bytes.
44       4      Most significant 4 bytes of second scan criteria operand. If second operand
                is less than 4 bytes, the value is left-aligned to the lowest address bytes.
48       8      Output (same fields as Primary Input)
56       8      Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
                “Extract command”
64       4      Next 4 most significant bytes of first scan criteria operand occuring after the
                bytes specified at offset 40, if needed by the operand size. If first operand
                is less than 8 bytes, the valid bytes are left-aligned to the lowest address.
68       4      Next 4 most significant bytes of second scan criteria operand occuring after
                the bytes specified at offset 44, if needed by the operand size. If second
                operand is less than 8 bytes, the valid bytes are left-aligned to the lowest
                address.
72       4      Next 4 most significant bytes of first scan criteria operand occuring after the
                bytes specified at offset 64, if needed by the operand size. If first operand
                is less than 12 bytes, the valid bytes are left-aligned to the lowest address.
76       4      Next 4 most significant bytes of second scan criteria operand occuring after
                the bytes specified at offset 68, if needed by the operand size. If second
                operand is less than 12 bytes, the valid bytes are left-aligned to the lowest
                address.
80       4      Next 4 most significant bytes of first scan criteria operand occuring after the
                bytes specified at offset 72, if needed by the operand size. If first operand
                is less than 16 bytes, the valid bytes are left-aligned to the lowest address.
84       4      Next 4 most significant bytes of second scan criteria operand occuring after
                the bytes specified at offset 76, if needed by the operand size. If second
                operand is less than 16 bytes, the valid bytes are left-aligned to the lowest
                address.




                                521
                                               Coprocessor services


36.2.1.4. Translate commands

        The translate commands takes an input array of indicies, and a table of single bit values indexed by those
        indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in
        the input array. The output should therefore contain exactly one bit per index in the input data stream,
        when outputing as a bit vector. When outputing as an index array, the number of elements depends on the
        values read in the bit table, but will always be less than, or equal to, the number of input elements. Only
        a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP
        encoded input streams are allowed. The primary input data element size must be 3 bytes or less.

        The maximum table index size allowed is 15 bits, however, larger input elements may be used to provide
        additional processing of the output values. If 2 or 3 byte values are used, the least significant 15 bits are
        used as an index into the bit table. The most significant 9 bits (when using 3-byte input elements) or single
        bit (when using 2-byte input elements) are compared against a fixed 9-bit test value provided in the CCB.
        If the values match, the value from the bit table is used as the output element value. If the values do not
        match, the output data element value is forced to 0.

        In the inverted translate operation, the bit value read from bit table is inverted prior to its use. The additional
        additional processing based on any additional non-index bits remains unchanged, and still forces the output
        element value to 0 on a mismatch. The specific type of translate command is indicated by the command
        code in the CCB header.

        There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
        0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the
        output format was a bit array.

        The return value of the CCB completion area contains the number of bits set in the output bit vector,
        or number of elements in the output index array. The “number of elements processed” field in the CCB
        completion area will be valid, indicating the number of input elements processed.

        These commands are 64-byte “short format” CCBs.

        The translate CCB command format can be specified by the following packed C structure for a big-endian
        machine:


                 struct translate_ccb {
                        uint32_t header;
                        uint32_t control;
                        uint64_t completion;
                        uint64_t primary_input;
                        uint64_t data_access_control;
                        uint64_t secondary_input;
                        uint64_t reserved;
                        uint64_t output;
                        uint64_t table;
                 };


        The exact field offsets, sizes, and composition are as follows:


        Offset          Size             Field Description
        0               4                CCB header (Table 36.1, “CCB Header Format”)


                                                        522
                        Coprocessor services


Offset   Size   Field Description
4        4      Command control
                Bits         Field Description
                [31:28]      Primary Input Format (see Section 36.2.1.1.1, “Primary Input
                             Format”)
                [27:23]      Primary Input Element Size (see Section 36.2.1.1.2, “Primary
                             Input Element Size”)
                [22:20]      Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
                             Element Offsets”)
                [19]         Secondary Input Format (see Section 36.2.1.1.3, “Secondary
                             Input Format”)
                [18:16]      Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
                             Element Offsets”)
                [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
                             “Secondary Input Element Size”
                [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
                [9]          Reserved
                [8:0]        Test value used for comparison against the most significant bits
                             in the input values, when using 2 or 3 byte input elements.
8        8      Completion (same fields as Section 36.2.1.2, “Extract command”
16       8      Primary Input (same fields as Section 36.2.1.2, “Extract command”
24       8      Data Access Control (same fields as Section 36.2.1.2, “Extract command”,
                except Primary Input Length Format may not use the 0x0 value)
32       8      Secondary Input, if used by Primary Input Format. Same fields as Primary
                Input.
40       8      Reserved
48       8      Output (same fields as Primary Input)
56       8      Bit Table
                Bits         Field Description
                [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
                             Integrity (ADI)”)
                [59:56]      If using real address, these bits should be filled in with the
                             page size code for the page boundary checking the guest wants
                             the virtual machine to use when accessing this data stream
                             (checking is only guaranteed to be performed when using API
                             version 1.1 and later). If using a virtual address, this field will
                             be used as as bit table address bits [59:56]
                [55:4]       Bit table address bits [55:4]. Address type is determined by
                             CCB header. Address must be 64-byte aligned (CCB version
                             0) or 16-byte aligned (CCB version 1).
                [3:0]        Bit table version
                             Value      Description
                             0          4KB table size
                             1          8KB table size



                                 523
                                              Coprocessor services


36.2.1.5. Select command
        The select command filters the primary input data stream by using a secondary input bit vector to determine
        which input elements to include in the output. For each bit set at a given index N within the bit vector,
        the Nth input element is included in the output. If the bit is not set, the element is not included. Only a
        restricted subset of the possible input format types are supported. No variable width or run length encoded
        input streams are allowed, since the secondary input stream is used for the filtering bit vector.

        The only supported output format is a padded, byte-aligned output stream. The stream follows the same
        rules and restrictions as padded output stream described in Section 36.2.1.2, “Extract command”.

        The return value of the CCB completion area contains the number of bits set in the input bit vector. The
        "number of elements processed" field in the CCB completion area will be valid, indicating the number
        of input elements processed.

        The select CCB is a 64-byte “short format” CCB.

        The select CCB command format can be specified by the following packed C structure for a big-endian
        machine:


                  struct select_ccb {
                         uint32_t header;
                         uint32_t control;
                         uint64_t completion;
                         uint64_t primary_input;
                         uint64_t data_access_control;
                         uint64_t secondary_input;
                         uint64_t reserved;
                         uint64_t output;
                         uint64_t table;
                  };


        The exact field offsets, sizes, and composition are as follows:

         Offset        Size            Field Description
         0             4               CCB header (Table 36.1, “CCB Header Format”)
         4             4               Command control
                                       Bits        Field Description
                                       [31:28]     Primary Input Format (see Section 36.2.1.1.1, “Primary Input
                                                   Format”)
                                       [27:23]     Primary Input Element Size (see Section 36.2.1.1.2, “Primary
                                                   Input Element Size”)
                                       [22:20]     Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                                   Element Offsets”)
                                       [19]        Secondary Input Format (see Section 36.2.1.1.3, “Secondary
                                                   Input Format”)
                                       [18:16]     Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
                                                   Element Offsets”)
                                       [15:14]     Secondary Input Element Size (see Section 36.2.1.1.4,
                                                   “Secondary Input Element Size”


                                                      524
                                               Coprocessor services


        Offset         Size            Field Description
                                       Bits         Field Description
                                       [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
                                       [9]          Padding Direction selector: A value of 1 causes padding bytes
                                                    to be added to the left side of output elements. A value of 0
                                                    causes padding bytes to be added to the right side of output
                                                    elements.
                                       [8:0]        Reserved
        8              8               Completion (same fields as Section 36.2.1.2, “Extract command”
        16             8               Primary Input (same fields as Section 36.2.1.2, “Extract command”
        24             8               Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
        32             8               Secondary Bit Vector Input. Same fields as Primary Input.
        40             8               Reserved
        48             8               Output (same fields as Primary Input)
        56             8               Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
                                       “Extract command”

36.2.1.6. No-op and Sync commands
        The no-op (no operation) command is a CCB which has no processing effect. The CCB, when processed
        by the virtual machine, simply updates the completion area with its execution status. The CCB may have
        the serial-conditional flags set in order to restrict when it executes.

        The sync command is a variant of the no-op command which with restricted execution timing. A sync
        command CCB will only execute when all previous commands submitted in the same request have
        completed. This is stronger than the conditional flag sequencing, which is only dependent on a single
        previous serial CCB. While the relative ordering is guaranteed, virtual machine implementations with
        shared hardware resources may cause the sync command to wait for longer than the minimum required
        time.

        The return value of the CCB completion area is invalid for these CCBs. The “number of elements
        processed” field is also invalid for these CCBs.

        These commands are 64-byte “short format” CCBs.

        The no-op CCB command format can be specified by the following packed C structure for a big-endian
        machine:


                 struct nop_ccb {
                        uint32_t header;
                        uint32_t control;
                        uint64_t completion;
                        uint64_t reserved[6];
                 };


        The exact field offsets, sizes, and composition are as follows:

        Offset         Size            Field Description
        0              4               CCB header (Table 36.1, “CCB Header Format”)


                                                       525
                                          Coprocessor services


       Offset        Size          Field Description
       4             4             Command control
                                   Bits        Field Description
                                   [31]        If set, this CCB functions as a Sync command. If clear, this
                                               CCB functions as a No-op command.
                                   [30:0]      Reserved
       8             8             Completion (same fields as Section 36.2.1.2, “Extract command”
       16            46            Reserved

36.2.2. CCB Completion Area
       All CCB commands use a common 128-byte Completion Area format, which can be specified by the
       following packed C structure for a big-endian machine:


                struct completion_area {
                       uint8_t status_flag;
                       uint8_t error_note;
                       uint8_t rsvd0[2];
                       uint32_t error_values;
                       uint32_t output_size;
                       uint32_t rsvd1;
                       uint64_t run_time;
                       uint64_t run_stats;
                       uint32_t elements;
                       uint8_t rsvd2[20];
                       uint64_t return_value;
                       uint64_t extra_return_value[8];
                };


       The Completion Area must be a 128-byte aligned memory location. The exact layout can be described
       using byte offsets and sizes relative to the memory base:

       Offset        Size          Field Description
       0             1             CCB execution status
                                   0x0                  Command not yet completed
                                   0x1                  Command ran and succeeded
                                   0x2                  Command ran and failed (partial results may be been
                                                        produced)
                                   0x3                  Command ran and was killed (partial execution may
                                                        have occurred)
                                   0x4                  Command was not run
                                   0x5-0xF              Reserved
       1             1             Error reason code
                                   0x0                  Reserved
                                   0x1                  Buffer overflow


                                                  526
                                      Coprocessor services


Offset          Size           Field Description
                                0x2                 CCB decoding error
                                0x3                 Page overflow
                                0x4-0x6             Reserved
                                0x7                 Command was killed
                                0x8                 Command execution timeout
                                0x9                 ADI miscompare error
                                0xA                 Data format error
                                0xB-0xD             Reserved
                                0xE                 Unexpected hardware error (Do not retry)
                                0xF                 Unexpected hardware error (Retry is ok)
                                0x10-0x7F           Reserved
                                0x80                Partial Symbol Warning
                                0x81-0xFF           Reserved
2               2              Reserved
4               4              If a partial symbol warning was generated, this field contains the number
                               of remaining bits which were not decoded.
8               4              Number of bytes of output produced
12              4              Reserved
16              8              Runtime of command (unspecified time units)
24              8              Reserved
32              4              Number of elements processed
36              20             Reserved
56              8              Return value
64              64             Extended return value

The CCB completion area should be treated as read-only by guest software. The CCB execution status
byte will be cleared by the Hypervisor to reflect the pending execution status when the CCB is submitted
successfully. All other fields are considered invalid upon CCB submission until the CCB execution status
byte becomes non-zero.

CCBs which complete with status 0x2 or 0x3 may produce partial results and/or side effects due to partial
execution of the CCB command. Some valid data may be accessible depending on the fault type, however,
it is recommended that guest software treat the destination buffer as being in an unknown state. If a CCB
completes with a status byte of 0x2, the error reason code byte can be read to determine what corrective
action should be taken.

A buffer overflow indicates that the results of the operation exceeded the size of the output buffer indicated
in the CCB. The operation can be retried by resubmitting the CCB with a larger output buffer.

A CCB decoding error indicates that the CCB contained some invalid field values. It may be also be
triggered if the CCB output is directed at a non-existent secondary input and the pipelining hint is followed.

A page overflow error indicates that the operation required accessing a memory location beyond the page
size associated with a given address. No data will have been read or written past the page boundary, but
partial results may have been written to the destination buffer. The CCB can be resubmitted with a larger
page size memory allocation to complete the operation.


                                              527
                                            Coprocessor services


       In the case of pipelined CCBs, a page overflow error will be triggered if the output from the pipeline source
       CCB ends before the input of the pipeline target CCB. Page boundaries are ignored when the pipeline
       hint is followed.

       Command kill indicates that the CCB execution was halted or prevented by use of the ccb_kill API call.

       Command timeout indicates that the CCB execution began, but did not complete within a pre-determined
       limit set by the virtual machine. The command may have produced some or no output. The CCB may be
       resubmitted with no alterations.

       ADI miscompare indicates that the memory buffer version specified in the CCB did not match the value
       in memory when accessed by the virtual machine. Guest software should not attempt to resubmit the CCB
       without determining the cause of the version mismatch.

       A data format error indicates that the input data stream did not follow the specified data input formatting
       selected in the CCB.

       Some CCBs which encounter hardware errors may be resubmitted without change. Persistent hardware
       errors may result in multiple failures until RAS software can identify and isolate the faulty component.

       The output size field indicates the number of bytes of valid output in the destination buffer. This field is
       not valid for all possible CCB commands.

       The runtime field indicates the execution time of the CCB command once it leaves the internal virtual
       machine queue. The time units are fixed, but unspecified, allowing only relative timing comparisons
       by guest software. The time units may also vary by hardware platform, and should not be construed to
       represent any absolute time value.

       Some data query commands process data in units of elements. If applicable to the command, the number of
       elements processed is indicated in the listed field. This field is not valid for all possible CCB commands.

       The return value and extended return value fields are output locations for commands which do not use
       a destination output buffer, or have secondary return results. The field is not valid for all possible CCB
       commands.

36.3. Hypervisor API Functions
36.3.1. ccb_submit
       trap#             FAST_TRAP
       function#         CCB_SUBMIT
       arg0              address
       arg1              length
       arg2              flags
       arg3              reserved
       ret0              status
       ret1              length
       ret2              status data
       ret3              reserved

       Submit one or more coprocessor control blocks (CCBs) for evaluation and processing by the virtual
       machine. The CCBs are passed in a linear array indicated by address. length indicates the size of
       the array in bytes.


                                                     528
                                      Coprocessor services


The address should be aligned to the size indicated by length, rounded up to the nearest power of
two. Virtual machines implementations may reject submissions which do not adhere to that alignment.
length must be a multiple of 64 bytes. If length is zero, the maximum supported array length will be
returned as length in ret1. In all other cases, the length value in ret1 will reflect the number of bytes
successfully consumed from the input CCB array.

      Implementation note
      Virtual machines should never reject submissions based on the alignment of address if the
      entire array is contained within a single memory page of the smallest page size supported by the
      virtual machine.

A guest may choose to submit addresses used in this API function, including the CCB array address,
as either a real or virtual addresses, with the type of each address indicated in flags. Virtual addresses
must be present in either the TLB or an active TSB to be processed. The translation context for virtual
addresses is determined by a combination of CCB contents and the flags argument.

The flags argument is divided into multiple fields defined as follows:


Bits            Field Description
[63:16]         Reserved
[15]            Disable ADI for VA reads (in API 2.0)
                Reserved (in API 1.0)
[14]            Virtual addresses within CCBs are translated in privileged context
[13:12]         Alternate translation context for virtual addresses within CCBs:
                 0b'00        CCBs requesting alternate context are rejected
                 0b'01        Reserved
                 0b'10        CCBs requesting alternate context use secondary context
                 0b'11        CCBs requesting alternate context use nucleus context
[11:9]          Reserved
[8]             Queue info flag
[7]             All-or-nothing flag
[6]             If address is a virtual address, treat its translation context as privileged
[5:4]           Address type of address:
                 0b'00        Real address
                 0b'01        Virtual address in primary context
                 0b'10        Virtual address in secondary context
                 0b'11        Virtual address in nucleus context
[3:2]           Reserved
[1:0]           CCB command type:
                 0b'00        Reserved
                 0b'01        Reserved
                 0b'10        Query command
                 0b'11        Reserved



                                              529
                                             Coprocessor services


         The CCB submission type and address type for the CCB array must be provided in the flags argument.
         All other fields are optional values which change the default behavior of the CCB processing.

         When set to one, the "Disable ADI for VA reads" bit will turn off ADI checking when using a virtual
         address to load data. ADI checking will still be done when loading real-addressed memory. This bit is only
         available when using major version 2 of the coprocessor API group; at major version 1 it is reserved. For
         more information about using ADI and DAX, see Section 36.2.1.1.7, “Application Data Integrity (ADI)”.

         By default, all virtual addresses are treated as user addresses. If the virtual address translations are
         privileged, they must be marked as such in the appropriate flags field. The virtual addresses used within
         the submitted CCBs must all be translated with the same privilege level.

         By default, all virtual addresses used within the submitted CCBs are translated using the primary context
         active at the time of the submission. The address type field within a CCB allows each address to request
         translation in an alternate address context. The address context used when the alternate address context is
         requested is selected in the flags argument.

         The all-or-nothing flag specifies whether the virtual machine should allow partial submissions of the
         input CCB array. When using CCBs with serial-conditional flags, it is strongly recommended to use
         the all-or-nothing flag to avoid broken conditional chains. Using long CCB chains on a machine under
         high coprocessor load may make this impractical, however, and require submitting without the flag.
         When submitting serial-conditional CCBs without the all-or-nothing flag, guest software must manually
         implement the serial-conditional behavior at any point where the chain was not submitted in a single API
         call, and resubmission of the remaining CCBs should clear any conditional flag that might be set in the
         first remaining CCB. Failure to do so will produce indeterminate CCB execution status and ordering.

         When the all-or-nothing flag is not specified, callers should check the value of length in ret1 to determine
         how many CCBs from the array were successfully submitted. Any remaining CCBs can be resubmitted
         without modifications.

         The value of length in ret1 is also valid when the API call returns an error, and callers should always
         check its value to determine which CCBs in the array were already processed. This will additionally
         identify which CCB encountered the processing error, and was not submitted successfully.

         If the queue info flag is used during submission, and at least one CCB was successfully submitted, the
         length value in ret1 will be a multi-field value defined as follows:
          Bits          Field Description
          [63:48]       DAX unit instance identifier
          [47:32]       DAX queue instance identifier
          [31:16]       Reserved
          [15:0]        Number of CCB bytes successfully submitted

         The value of status data depends on the status value. See error status code descriptions for details.
         The value is undefined for status values that do not specifically list a value for the status data.

         The API has a reserved input and output register which will be used in subsequent minor versions of this
         API function. Guest software implementations should treat that register as voltile across the function call
         in order to maintain forward compatibility.

36.3.1.1. Errors
          EOK                       One or more CCBs have been accepted and enqueued in the virtual machine
                                    and no errors were been encountered during submission. Some submitted
                                    CCBs may not have been enqueued due to internal virtual machine limitations,
                                    and may be resubmitted without changes.


                                                       530
                        Coprocessor services


EWOULDBLOCK    An internal resource conflict within the virtual machine has prevented it from
               being able to complete the CCB submissions sufficiently quickly, requiring
               it to abandon processing before it was complete. Some CCBs may have been
               successfully enqueued prior to the block, and all remaining CCBs may be
               resubmitted without changes.
EBADALIGN      CCB array is not on a 64-byte boundary, or the array length is not a multiple
               of 64 bytes.
ENORADDR       A real address used either for the CCB array, or within one of the submitted
               CCBs, is not valid for the guest. Some CCBs may have been enqueued prior
               to the error being detected.
ENOMAP         A virtual address used either for the CCB array, or within one of the submitted
               CCBs, could not be translated by the virtual machine using either the TLB
               or TSB contents. The submission may be retried after adding the required
               mapping, or by converting the virtual address into a real address. Due to the
               shared nature of address translation resources, there is no theoretical limit on
               the number of times the translation may fail, and it is recommended all guests
               implement some real address based backup. The virtual address which failed
               translation is returned as status data in ret2. Some CCBs may have been
               enqueued prior to the error being detected.
EINVAL         The virtual machine detected an invalid CCB during submission, or invalid
               input arguments, such as bad flag values. Note that not all invalid CCB values
               will be detected during submission, and some may be reported as errors in the
               completion area instead. Some CCBs may have been enqueued prior to the
               error being detected. This error may be returned if the CCB version is invalid.
ETOOMANY       The request was submitted with the all-or-nothing flag set, and the array size is
               greater than the virtual machine can support in a single request. The maximum
               supported size for the current virtual machine can be queried by submitting a
               request with a zero length array, as described above.
ENOACCESS      The guest does not have permission to submit CCBs, or an address used in a
               CCBs lacks sufficient permissions to perform the required operation (no write
               permission on the destination buffer address, for example). A virtual address
               which fails permission checking is returned as status data in ret2. Some
               CCBs may have been enqueued prior to the error being detected.
EUNAVAILABLE   The requested CCB operation could not be performed at this time. The
               restricted operation availability may apply only to the first unsuccessfully
               submitted CCB, or may apply to a larger scope. The status should not be
               interpreted as permanent, and the guest should attempt to submit CCBs in
               the future which had previously been unable to be performed. The status
               data provides additional information about scope of the retricted availability
               as follows:
               Value       Description
               0           Processing for the exact CCB instance submitted was unavailable,
                           and it is recommended the guest emulate the operation. The
                           guest should continue to submit all other CCBs, and assume no
                           restrictions beyond this exact CCB instance.
               1           Processing is unavailable for all CCBs using the requested opcode,
                           and it is recommended the guest emulate the operation. The
                           guest should continue to submit all other CCBs that use different
                           opcodes, but can expect continued rejections of CCBs using the
                           same opcode in the near future.


                                 531
                                              Coprocessor services


                                      Value     Description
                                      2         Processing is unavailable for all CCBs using the requested CCB
                                                version, and it is recommended the guest emulate the operation.
                                                The guest should continue to submit all other CCBs that use
                                                different CCB versions, but can expect continued rejections of
                                                CCBs using the same CCB version in the near future.
                                      3         Processing is unavailable for all CCBs on the submitting vcpu,
                                                and it is recommended the guest emulate the operation or resubmit
                                                the CCB on a different vcpu. The guest should continue to submit
                                                CCBs on all other vcpus but can expect continued rejections of all
                                                CCBs on this vcpu in the near future.
                                      4         Processing is unavailable for all CCBs, and it is recommended
                                                the guest emulate the operation. The guest should expect all CCB
                                                submissions to be similarly rejected in the near future.


36.3.2. ccb_info

        trap#               FAST_TRAP
        function#           CCB_INFO
        arg0                address
        ret0                status
        ret1                CCB state
        ret2                position
        ret3                dax
        ret4                queue

       Requests status information on a previously submitted CCB. The previously submitted CCB is identified
       by the 64-byte aligned real address of the CCBs completion area.

       A CCB can be in one of 4 states:


        State                     Value       Description
        COMPLETED                 0           The CCB has been fetched and executed, and is no longer active in
                                              the virtual machine.
        ENQUEUED                  1           The requested CCB is current in a queue awaiting execution.
        INPROGRESS                2           The CCB has been fetched and is currently being executed. It may still
                                              be possible to stop the execution using the ccb_kill hypercall.
        NOTFOUND                  3           The CCB could not be located in the virtual machine, and does not
                                              appear to have been executed. This may occur if the CCB was lost
                                              due to a hardware error, or the CCB may not have been successfully
                                              submitted to the virtual machine in the first place.

               Implementation note
               Some platforms may not be able to report CCBs that are currently being processed, and therefore
               guest software should invoke the ccb_kill hypercall prior to assuming the request CCB will never
               be executed because it was in the NOTFOUND state.


                                                       532
                                             Coprocessor services


         The position return value is only valid when the state is ENQUEUED. The value returned is the number
         of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute.

         The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit
         instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value
         matches the value that would have been, or was, returned by ccb_submit using the queue info flag.

         The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX
         queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The
         value matches the value that would have been, or was, returned by ccb_submit using the queue info flag.

36.3.2.1. Errors

          EOK                       The request was proccessed and the CCB state is valid.
          EBADALIGN                 address is not on a 64-byte aligned.
          ENORADDR                  The real address provided for address is not valid.
          EINVAL                    The CCB completion area contents are not valid.
          EWOULDBLOCK               Internal resource contraints prevented the CCB state from being queried at this
                                    time. The guest should retry the request.
          ENOACCESS                 The guest does not have permission to access the coprocessor virtual device
                                    functionality.

36.3.3. ccb_kill

          trap#           FAST_TRAP
          function#       CCB_KILL
          arg0            address
          ret0            status
          ret1            result

         Request to stop execution of a previously submitted CCB. The previously submitted CCB is identified by
         the 64-byte aligned real address of the CCBs completion area.

         The kill attempt can produce one of several values in the result return value, reflecting the CCB state
         and actions taken by the Hypervisor:

          Result                Value       Description
          COMPLETED             0           The CCB has been fetched and executed, and is no longer active in
                                            the virtual machine. It could not be killed and no action was taken.
          DEQUEUED              1           The requested CCB was still enqueued when the kill request was
                                            submitted, and has been removed from the queue. Since the CCB
                                            never began execution, no memory modifications were produced by
                                            it, and the completion area will never be updated. The same CCB may
                                            be submitted again, if desired, with no modifications required.
          KILLED                2           The CCB had been fetched and was being executed when the kill
                                            request was submitted. The CCB execution was stopped, and the CCB
                                            is no longer active in the virtual machine. The CCB completion area
                                            will reflect the killed status, with the subsequent implications that
                                            partial results may have been produced. Partial results may include full


                                                      533
                                              Coprocessor services


          Result                 Value       Description
                                             command execution if the command was stopped just prior to writing
                                             to the completion area.
          NOTFOUND               3           The CCB could not be located in the virtual machine, and does not
                                             appear to have been executed. This may occur if the CCB was lost
                                             due to a hardware error, or the CCB may not have been successfully
                                             submitted to the virtual machine in the first place. CCBs in the state
                                             are guaranteed to never execute in the future unless resubmitted.

36.3.3.1. Interactions with Pipelined CCBs

         If the pipeline target CCB is killed but the pipeline source CCB was skipped, the completion area of the
         target CCB may contain status (4,0) "Command was skipped" instead of (3,7) "Command was killed".

         If the pipeline source CCB is killed, the pipeline target CCB's completion status may read (1,0) "Success".
         This does not mean the target CCB was processed; since the source CCB was killed, there was no
         meaningful output on which the target CCB could operate.

36.3.3.2. Errors

          EOK                        The request was proccessed and the result is valid.
          EBADALIGN                  address is not on a 64-byte aligned.
          ENORADDR                   The real address provided for address is not valid.
          EINVAL                     The CCB completion area contents are not valid.
          EWOULDBLOCK                Internal resource contraints prevented the CCB from being killed at this time.
                                     The guest should retry the request.
          ENOACCESS                  The guest does not have permission to access the coprocessor virtual device
                                     functionality.

36.3.4. dax_info
          trap#            FAST_TRAP
          function#        DAX_INFO
          ret0             status
          ret1             Number of enabled DAX units
          ret2             Number of disabled DAX units

         Returns the number of DAX units that are enabled for the calling guest to submit CCBs. The number of
         DAX units that are disabled for the calling guest are also returned. A disabled DAX unit would have been
         available for CCB submission to the calling guest had it not been offlined.

36.3.4.1. Errors

          EOK                        The request was proccessed and the number of enabled/disabled DAX units
                                     are valid.




                                                       534