Documentation/sparc/oradax/dax-hv-api.txt

   1 Excerpt from UltraSPARC Virtual Machine Specification
   2 Compiled from version 3.0.20+15
   3 Publication date 2017-09-25 08:21
   4 Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved.
   5 Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf"
   6 Authors:
   7          Charles Kunzman
   8          Sam Glidden
   9          Mark Cianchetti
  10
  11
  12 Chapter 36. Coprocessor services
  13         The following APIs provide access via the Hypervisor to hardware assisted data processing functionality.
  14         These APIs may only be provided by certain platforms, and may not be available to all virtual machines
  15         even on supported platforms. Restrictions on the use of these APIs may be imposed in order to support
  16         live-migration and other system management activities.
  17
  18 36.1. Data Analytics Accelerator
  19         The Data Analytics Accelerator (DAX) functionality is a collection of hardware coprocessors that provide
  20         high speed processoring of database-centric operations. The coprocessors may support one or more of
  21         the following data query operations: search, extraction, compression, decompression, and translation. The
  22         functionality offered may vary by virtual machine implementation.
  23
  24         The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device
  25         compatibilty property. Functionality is accessed through the submission of Command Control Blocks
  26         (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status
  27         of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a
  28         separate Completion Area and, unless execution order is specifically restricted through the use of serial-
  29         conditional flags, the execution order of submitted CCBs is arbitrary. Likewise, the time to completion
  30         for a given CCB is never guaranteed.
  31
  32         Guest software may implement a software timeout on CCB operations, and if the timeout is exceeded, the
  33         operation may be cancelled or killed via the ccb_kill API function. It is recommended for guest software
  34         to implement a software timeout to account for certain RAS errors which may result in lost CCBs. It is
  35         recommended such implementation use the ccb_info API function to check the status of a CCB prior to
  36         killing it in order to determine if the CCB is still in queue, or may have been lost due to a RAS error.
  37
  38         There is no fixed limit on the number of outstanding CCBs guest software may have queued in the virtual
  39         machine, however, internal resource limitations within the virtual machine can cause CCB submissions
  40         to be temporarily rejected with EWOULDBLOCK. In such cases, guests should continue to attempt
  41         submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would
  42         not be a guarantee that a future submission would succeed.
  43
  44         The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual
  45         device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device
  46         node”).
  47
  48 36.1.1. DAX Compatibility Property
  49         The query functionality may vary based on the compatibility property of the virtual device:
  50
  51 36.1.1.1. "ORCL,sun4v-dax" Device Compatibility
  52         Available CCB commands:
  53
  54         • No-op/Sync
  55
  56         • Extract
  57
  58         • Scan Value
  59
  60         • Inverted Scan Value
  61
  62         • Scan Range
  63
  64
  65                                                      509
  66 \f                                             Coprocessor services
  67
  68
  69         • Inverted Scan Range
  70
  71         • Translate
  72
  73         • Inverted Translate
  74
  75         • Select
  76
  77         See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.
  78
  79         Only version 0 CCBs are available.
  80
  81 36.1.1.2. "ORCL,sun4v-dax-fc" Device Compatibility
  82         "ORCL,sun4v-dax-fc" is compatible with the "ORCL,sun4v-dax" interface, and includes additional CCB
  83         bit fields and controls.
  84
  85 36.1.1.3. "ORCL,sun4v-dax2" Device Compatibility
  86         Available CCB commands:
  87
  88         • No-op/Sync
  89
  90         • Extract
  91
  92         • Scan Value
  93
  94         • Inverted Scan Value
  95
  96         • Scan Range
  97
  98         • Inverted Scan Range
  99
 100         • Translate
 101
 102         • Inverted Translate
 103
 104         • Select
 105
 106         See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.
 107
 108         Version 0 and 1 CCBs are available. Only version 0 CCBs may use Huffman encoded data, whereas only
 109         version 1 CCBs may use OZIP.
 110
 111 36.1.2. DAX Virtual Device Interrupts
 112         The DAX virtual device has multiple interrupts associated with it which may be used by the guest if
 113         desired. The number of device interrupts available to the guest is indicated in the virtual device node of the
 114         guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). If the device
 115         node indicates N interrupts available, the guest may use any value from 0 to N - 1 (inclusive) in a CCB
 116         interrupt number field. Using values outside this range will result in the CCB being rejected for an invalid
 117         field value.
 118
 119         The interrupts may be bound and managed using the standard sun4v device interrupts API (Chapter 16,
 120         Device interrupt services). Sysino interrupts are not available for DAX devices.
 121
 122 36.2. Coprocessor Control Block (CCB)
 123         CCBs are either 64 or 128 bytes long, depending on the operation type. The exact contents of the CCB
 124         are command specific, but all CCBs contain at least one memory buffer address. All memory locations
 125
 126
 127                                                       510
 128 \f                                    Coprocessor services
 129
 130
 131 referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed
 132 via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not
 133 guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB
 134 execution.
 135
 136 All CCBs begin with a common 32-bit header.
 137
 138 Table 36.1. CCB Header Format
 139 Bits          Field Description
 140 [31:28]       CCB version. For API version 2.0: set to 1 if CCB uses OZIP encoding; set to 0 if the CCB
 141               uses Huffman encoding; otherwise either 0 or 1. For API version 1.0: always set to 0.
 142 [27]          When API version 2.0 is negotiated, this is the Pipeline Flag [512]. It is reserved in
 143               API version 1.0
 144 [26]          Long CCB flag [512]
 145 [25]          Conditional synchronization flag [512]
 146 [24]          Serial synchronization flag
 147 [23:16]       CCB operation code:
 148                0x00        No Operation (No-op) or Sync
 149                0x01        Extract
 150                0x02        Scan Value
 151                0x12        Inverted Scan Value
 152                0x03        Scan Range
 153                0x13        Inverted Scan Range
 154                0x04        Translate
 155                0x14        Inverted Translate
 156                0x05        Select
 157 [15:13]       Reserved
 158 [12:11]       Table address type
 159                0b'00       No address
 160                0b'01       Alternate context virtual address
 161                0b'10       Real address
 162                0b'11       Primary context virtual address
 163 [10:8]        Output/Destination address type
 164                0b'000      No address
 165                0b'001      Alternate context virtual address
 166                0b'010      Real address
 167                0b'011      Primary context virtual address
 168                0b'100      Reserved
 169                0b'101      Reserved
 170                0b'110      Reserved
 171                0b'111      Reserved
 172 [7:5]         Secondary source address type
 173
 174
 175                                             511
 176 \f                                    Coprocessor services
 177
 178
 179 Bits           Field Description
 180                 0b'000       No address
 181                 0b'001       Alternate context virtual address
 182                 0b'010       Real address
 183                 0b'011       Primary context virtual address
 184                 0b'100       Reserved
 185                 0b'101       Reserved
 186                 0b'110       Reserved
 187                 0b'111       Reserved
 188 [4:2]          Primary source address type
 189                 0b'000       No address
 190                 0b'001       Alternate context virtual address
 191                 0b'010       Real address
 192                 0b'011       Primary context virtual address
 193                 0b'100       Reserved
 194                 0b'101       Reserved
 195                 0b'110       Reserved
 196                 0b'111       Reserved
 197 [1:0]          Completion area address type
 198                 0b'00        No address
 199                 0b'01        Alternate context virtual address
 200                 0b'10        Real address
 201                 0b'11        Primary context virtual address
 202
 203 The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes
 204 and 1 for 128 bytes.
 205
 206 The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial
 207 flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same
 208 CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs
 209 with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the
 210 previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs
 211 to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag.
 212 A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional
 213 and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs
 214 execute in parallel based on the completion of another CCB.
 215
 216 The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to
 217 the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from
 218 memory. The Pipeline flag is advisory and may be dropped.
 219
 220 Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the
 221 target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs
 222 is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB
 223 with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional
 224 bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit.
 225
 226
 227                                              512
 228 \f                                               Coprocessor services
 229
 230
 231           The input of the target CCB must start within 64 bytes of the output of the source CCB or the pipeline flag
 232           will be ignored. All CCBs in a pipeline must be submitted in the same call to ccb_submit.
 233
 234           The various address type fields indicate how the various address values used in the CCB should be
 235           interpreted by the virtual machine. Not all of the types specified are used by every CCB format. Types
 236           which are not applicable to the given CCB command should be indicated as type 0 (No address). Virtual
 237           addresses used in the CCB must have translation entries present in either the TLB or a configured TSB
 238           for the submitting virtual processor. Virtual addresses which cannot be translated by the virtual machine
 239           will result in the CCB submission being rejected, with the causal virtual address indicated. The CCB
 240           may be resubmitted after inserting the translation, or the address may be translated by guest software and
 241           resubmitted using the real address translation.
 242
 243 36.2.1. Query CCB Command Formats
 244 36.2.1.1. Supported Data Formats, Elements Sizes and Offsets
 245           Data for query commands may be encoded in multiple possible formats. The data query commands use a
 246           common set of values to indicate the encoding formats of the data being processed. Some encoding formats
 247           require multiple data streams for processing, requiring the specification of both primary data formats (the
 248           encoded data) and secondary data streams (meta-data for the encoded data).
 249
 250 36.2.1.1.1. Primary Input Format
 251
 252           The primary input format code is a 4-bit field when it is used. There are 10 primary input formats available.
 253           The packed formats are not endian neutral. Code values not listed below are reserved.
 254
 255           Code        Format                              Description
 256           0x0         Fixed width byte packed             Up to 16 bytes
 257           0x1         Fixed width bit packed              Up to 15 bits (CCB version 0) or 23 bits (CCB version
 258                                                           1); bits are read most significant bit to least significant bit
 259                                                           within a byte
 260           0x2         Variable width byte packed          Data stream of lengths must be provided as a secondary
 261                                                           input
 262           0x4         Fixed width byte packed with run Up to 16 bytes; data stream of run lengths must be
 263                       length encoding                  provided as a secondary input
 264           0x5         Fixed width bit packed with run Up to 15 bits (CCB version 0) or 23 bits (CCB version
 265                       length encoding                 1); bits are read most significant bit to least significant bit
 266                                                       within a byte; data stream of run lengths must be provided
 267                                                       as a secondary input
 268           0x8         Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream
 269                       Huffman (CCB version 0) or bits are read most significant bit to least significant bit
 270                       OZIP (CCB version 1) encoding within a byte; pointer to the encoding table must be
 271                                                     provided
 272           0x9         Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits (CCB version
 273                       Huffman (CCB version 0) or 1); compressed stream bits are read most significant bit to
 274                       OZIP (CCB version 1) encoding least significant bit within a byte; pointer to the encoding
 275                                                     table must be provided
 276           0xA         Variable width byte packed with Up to 16 bytes before the encoding; compressed stream
 277                       Huffman (CCB version 0) or bits are read most significant bit to least significant bit
 278                       OZIP (CCB version 1) encoding within a byte; data stream of lengths must be provided as
 279                                                       a secondary input; pointer to the encoding table must be
 280                                                       provided
 281
 282
 283                                                         513
 284 \f                                               Coprocessor services
 285
 286
 287           Code        Format                              Description
 288           0xC         Fixed width byte packed with        Up to 16 bytes before the encoding; compressed stream
 289                       run length encoding, followed by    bits are read most significant bit to least significant bit
 290                       Huffman (CCB version 0) or          within a byte; data stream of run lengths must be provided
 291                       OZIP (CCB version 1) encoding       as a secondary input; pointer to the encoding table must
 292                                                           be provided
 293           0xD         Fixed width bit packed with         Up to 15 bits (CCB version 0) or 23 bits(CCB version 1)
 294                       run length encoding, followed by    before the encoding; compressed stream bits are read most
 295                       Huffman (CCB version 0) or          significant bit to least significant bit within a byte; data
 296                       OZIP (CCB version 1) encoding       stream of run lengths must be provided as a secondary
 297                                                           input; pointer to the encoding table must be provided
 298
 299           If OZIP encoding is used, there must be no reserved bytes in the table.
 300
 301 36.2.1.1.2. Primary Input Element Size
 302
 303           For primary input data streams with fixed size elements, the element size must be indicated in the CCB
 304           command. The size is encoded as the number of bits or bytes, minus one. The valid value range for this
 305           field depends on the input format selected, as listed in the table above.
 306
 307 36.2.1.1.3. Secondary Input Format
 308
 309           For primary input data streams which require a secondary input stream, the secondary input stream is
 310           always encoded in a fixed width, bit-packed format. The bits are read from most significant bit to least
 311           significant bit within a byte. There are two encoding options for the secondary input stream data elements,
 312           depending on whether the value of 0 is needed:
 313
 314           Secondary           Input Description
 315           Format Code
 316           0                          Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes
 317                                      to 2, etc)
 318           1                          Element is stored as value
 319
 320 36.2.1.1.4. Secondary Input Element Size
 321
 322           Secondary input element size is encoded as a two bit field:
 323
 324           Secondary Input Size Description
 325           Code
 326           0x0                        1 bit
 327           0x1                        2 bits
 328           0x2                        4 bits
 329           0x3                        8 bits
 330
 331 36.2.1.1.5. Input Element Offsets
 332
 333           Bit-wise input data streams may have any alignment within the base addressed byte. The offset, specified
 334           from most significant bit to least significant bit, is provided as a fixed 3 bit field for each input type. A
 335           value of 0 indicates that the first input element begins at the most significant bit in the first byte, and a
 336           value of 7 indicates it begins with the least significant bit.
 337
 338           This field should be zero for any byte-wise primary input data streams.
 339
 340
 341                                                         514
 342 \f                                              Coprocessor services
 343
 344
 345 36.2.1.1.6. Output Format
 346
 347           Query commands support multiple sizes and encodings for output data streams. There are four possible
 348           output encodings, and up to four supported element sizes per encoding. Not all output encodings are
 349           supported for every command. The format is indicated by a 4-bit field in the CCB:
 350
 351            Output Format Code        Description
 352            0x0                       Byte aligned, 1 byte elements
 353            0x1                       Byte aligned, 2 byte elements
 354            0x2                       Byte aligned, 4 byte elements
 355            0x3                       Byte aligned, 8 byte elements
 356            0x4                       16 byte aligned, 16 byte elements
 357            0x5                       Reserved
 358            0x6                       Reserved
 359            0x7                       Reserved
 360            0x8                       Packed vector of single bit elements
 361            0x9                       Reserved
 362            0xA                       Reserved
 363            0xB                       Reserved
 364            0xC                       Reserved
 365            0xD                       2 byte elements where each element is the index value of a bit,
 366                                      from an bit vector, which was 1.
 367            0xE                       4 byte elements where each element is the index value of a bit,
 368                                      from an bit vector, which was 1.
 369            0xF                       Reserved
 370
 371 36.2.1.1.7. Application Data Integrity (ADI)
 372
 373           On platforms which support ADI, the ADI version number may be specified for each separate memory
 374           access type used in the CCB command. ADI checking only occurs when reading data. When writing data,
 375           the specified ADI version number overwrites any existing ADI value in memory.
 376
 377           An ADI version value of 0 or 0xF indicates the ADI checking is disabled for that data access, even if it is
 378           enabled in memory. By setting the appropriate flag in CCB_SUBMIT (Section 36.3.1, “ccb_submit”) it is
 379           also an option to disable ADI checking for all inputs accessed via virtual address for all CCBs submitted
 380           during that hypercall invocation.
 381
 382           The ADI value is only guaranteed to be checked on the first 64 bytes of each data access. Mismatches on
 383           subsequent data chunks may not be detected, so guest software should be careful to use page size checking
 384           to protect against buffer overruns.
 385
 386 36.2.1.1.8. Page size checking
 387
 388           All data accesses used in CCB commands must be bounded within a single memory page. When addresses
 389           are provided using a virtual address, the page size for checking is extracted from the TTE for that virtual
 390           address. When using real addresses, the guest must supply the page size in the same field as the address
 391           value. The page size must be one of the sizes supported by the underlying virtual machine. Using a value
 392           that is not supported may result in the CCB submission being rejected or the generation of a CCB parsing
 393           error in the completion area.
 394
 395
 396                                                        515
 397 \f                                               Coprocessor services
 398
 399
 400 36.2.1.2. Extract command
 401
 402         Converts an input vector in one format to an output vector in another format. All input format types are
 403         supported.
 404
 405         The only supported output format is a padded, byte-aligned output stream, using output codes 0x0 - 0x4.
 406         When the specified output element size is larger than the extracted input element size, zeros are padded to
 407         the extracted input element. First, if the decompressed input size is not a whole number of bytes, 0 bits are
 408         padded to the most significant bit side till the next byte boundary. Next, if the output element size is larger
 409         than the byte padded input element, bytes of value 0 are added based on the Padding Direction bit in the
 410         CCB. If the output element size is smaller than the byte-padded input element size, the input element is
 411         truncated by dropped from the least significant byte side until the selected output size is reached.
 412
 413         The return value of the CCB completion area is invalid. The “number of elements processed” field in the
 414         CCB completion area will be valid.
 415
 416         The extract CCB is a 64-byte “short format” CCB.
 417
 418         The extract CCB command format can be specified by the following packed C structure for a big-endian
 419         machine:
 420
 421
 422                   struct extract_ccb {
 423                          uint32_t header;
 424                          uint32_t control;
 425                          uint64_t completion;
 426                          uint64_t primary_input;
 427                          uint64_t data_access_control;
 428                          uint64_t secondary_input;
 429                          uint64_t reserved;
 430                          uint64_t output;
 431                          uint64_t table;
 432                   };
 433
 434
 435         The exact field offsets, sizes, and composition are as follows:
 436
 437          Offset         Size            Field Description
 438          0              4               CCB header (Table 36.1, “CCB Header Format”)
 439          4              4               Command control
 440                                         Bits        Field Description
 441                                         [31:28]     Primary Input Format (see Section 36.2.1.1.1, “Primary Input
 442                                                     Format”)
 443                                         [27:23]     Primary Input Element Size (see Section 36.2.1.1.2, “Primary
 444                                                     Input Element Size”)
 445                                         [22:20]     Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
 446                                                     Element Offsets”)
 447                                         [19]        Secondary Input Format (see Section 36.2.1.1.3, “Secondary
 448                                                     Input Format”)
 449                                         [18:16]     Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
 450                                                     Element Offsets”)
 451
 452
 453                                                        516
 454 \f                        Coprocessor services
 455
 456
 457 Offset   Size   Field Description
 458                 Bits         Field Description
 459                 [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
 460                              “Secondary Input Element Size”
 461                 [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
 462                 [9]          Padding Direction selector: A value of 1 causes padding bytes
 463                              to be added to the left side of output elements. A value of 0
 464                              causes padding bytes to be added to the right side of output
 465                              elements.
 466                 [8:0]        Reserved
 467 8        8      Completion
 468                 Bits         Field Description
 469                 [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
 470                              Integrity (ADI)”)
 471                 [59]         If set to 1, a virtual device interrupt will be generated using
 472                              the device interrupt number specified in the lower bits of this
 473                              completion word. If 0, the lower bits of this completion word
 474                              are ignored.
 475                 [58:6]       Completion area address bits [58:6]. Address type is
 476                              determined by CCB header.
 477                 [5:0]        Virtual device interrupt number for completion interrupt, if
 478                              enabled.
 479 16       8      Primary Input
 480                 Bits         Field Description
 481                 [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
 482                              Integrity (ADI)”)
 483                 [59:56]      If using real address, these bits should be filled in with the
 484                              page size code for the page boundary checking the guest wants
 485                              the virtual machine to use when accessing this data stream
 486                              (checking is only guaranteed to be performed when using API
 487                              version 1.1 and later). If using a virtual address, this field will
 488                              be used as as primary input address bits [59:56].
 489                 [55:0]       Primary input address bits [55:0]. Address type is determined
 490                              by CCB header.
 491 24       8      Data Access Control
 492                 Bits         Field Description
 493                 [63:62]      Flow Control
 494                              Value      Description
 495                              0b'00      Disable flow control
 496                              0b'01      Enable flow control (only valid with "ORCL,sun4v-
 497                                         dax-fc" compatible virtual device variants)
 498                              0b'10      Reserved
 499                              0b'11      Reserved
 500                 [61:60]      Reserved (API 1.0)
 501
 502
 503                                 517
 504 \f                       Coprocessor services
 505
 506
 507 Offset   Size   Field Description
 508                 Bits        Field Description
 509                             Pipeline target (API 2.0)
 510                             Value      Description
 511                             0b'00      Connect to primary input
 512                             0b'01      Connect to secondary input
 513                             0b'10      Reserved
 514                             0b'11      Reserved
 515                 [59:40]     Output buffer size given in units of 64 bytes, minus 1. Value of
 516                             0 means 64 bytes, value of 1 means 128 bytes, etc. Buffer size is
 517                             only enforced if flow control is enabled in Flow Control field.
 518                 [39:32]     Reserved
 519                 [31:30]     Output Data Cache Allocation
 520                             Value      Description
 521                             0b'00      Do not allocate cache lines for output data stream.
 522                             0b'01      Force cache lines for output data stream to be
 523                                        allocated in the cache that is local to the submitting
 524                                        virtual cpu.
 525                             0b'10      Allocate cache lines for output data stream, but allow
 526                                        existing cache lines associated with the data to remain
 527                                        in their current cache instance. Any memory not
 528                                        already in cache will be allocated in the cache local
 529                                        to the submitting virtual cpu.
 530                             0b'11      Reserved
 531                 [29:26]     Reserved
 532                 [25:24]     Primary Input Length Format
 533                             Value      Description
 534                             0b'00      Number of primary symbols
 535                             0b'01      Number of primary bytes
 536                             0b'10      Number of primary bits
 537                             0b'11      Reserved
 538                 [23:0]      Primary Input Length
 539                             Format                      Field Value
 540                             # of primary symbols        Number of input elements to process,
 541                                                         minus 1. Command execution stops
 542                                                         once count is reached.
 543                             # of primary bytes          Number of input bytes to process,
 544                                                         minus 1. Command execution stops
 545                                                         once count is reached. The count is
 546                                                         done before any decompression or
 547                                                         decoding.
 548                             # of primary bits           Number of input bits to process,
 549                                                         minus 1. Command execution stops
 550
 551
 552
 553                                518
 554 \f                                                Coprocessor services
 555
 556
 557         Offset          Size           Field Description
 558                                         Bits         Field Description
 559                                                      Format                     Field Value
 560                                                                                 once count is reached. The count is
 561                                                                                 done before any decompression or
 562                                                                                 decoding, and does not include any
 563                                                                                 bits skipped by the Primary Input
 564                                                                                 Offset field value of the command
 565                                                                                 control word.
 566         32              8              Secondary Input, if used by Primary Input Format. Same fields as Primary
 567                                        Input.
 568         40              8              Reserved
 569         48              8              Output (same fields as Primary Input)
 570         56              8              Symbol Table (if used by Primary Input)
 571                                         Bits         Field Description
 572                                         [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
 573                                                      Integrity (ADI)”)
 574                                         [59:56]      If using real address, these bits should be filled in with the
 575                                                      page size code for the page boundary checking the guest wants
 576                                                      the virtual machine to use when accessing this data stream
 577                                                      (checking is only guaranteed to be performed when using API
 578                                                      version 1.1 and later). If using a virtual address, this field will
 579                                                      be used as as symbol table address bits [59:56].
 580                                         [55:4]       Symbol table address bits [55:4]. Address type is determined
 581                                                      by CCB header.
 582                                         [3:0]        Symbol table version
 583                                                      Value     Description
 584                                                      0         Huffman encoding. Must use 64 byte aligned table
 585                                                                address. (Only available when using version 0 CCBs)
 586                                                      1         OZIP encoding. Must use 16 byte aligned table
 587                                                                address. (Only available when using version 1 CCBs)
 588
 589
 590 36.2.1.3. Scan commands
 591
 592         The scan commands search a stream of input data elements for values which match the selection criteria.
 593         All the input format types are supported. There are multiple formats for the scan commands, allowing the
 594         scan to search for exact matches to one value, exact matches to either of two values, or any value within
 595         a specified range. The specific type of scan is indicated by the command code in the CCB header. For the
 596         scan range commands, the boundary conditions can be specified as greater-than-or-equal-to a value, less-
 597         than-or-equal-to a value, or both by using two boundary values.
 598
 599         There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
 600         0xD, and 0xE). For the standard scan command using the bit vector output, for each input element there
 601         exists one bit in the vector that is set if the input element matched the scan criteria, or clear if not. The
 602         inverted scan command inverts the polarity of the bits in the output. The most significant bit of the first
 603         byte of the output stream corresponds to the first element in the input stream. The standard index array
 604         output format contains one array entry for each input element that matched the scan criteria. Each array
 605
 606
 607
 608                                                          519
 609 \f                                       Coprocessor services
 610
 611
 612 entry is the index of an input element that matched the scan criteria. An inverted scan command produces
 613 a similar array, but of all the input elements which did NOT match the scan criteria.
 614
 615 The return value of the CCB completion area contains the number of input elements found which match
 616 the scan criteria (or number that did not match for the inverted scans). The “number of elements processed”
 617 field in the CCB completion area will be valid, indicating the number of input elements processed.
 618
 619 These commands are 128-byte “long format” CCBs.
 620
 621 The scan CCB command format can be specified by the following packed C structure for a big-endian
 622 machine:
 623
 624
 625          struct scan_ccb         {
 626                 uint32_t         header;
 627                 uint32_t         control;
 628                 uint64_t         completion;
 629                 uint64_t         primary_input;
 630                 uint64_t         data_access_control;
 631                 uint64_t         secondary_input;
 632                 uint64_t         match_criteria0;
 633                 uint64_t         output;
 634                 uint64_t         table;
 635                 uint64_t         match_criteria1;
 636                 uint64_t         match_criteria2;
 637                 uint64_t         match_criteria3;
 638                 uint64_t         reserved[5];
 639          };
 640
 641
 642 The exact field offsets, sizes, and composition are as follows:
 643
 644 Offset         Size            Field Description
 645 0              4               CCB header (Table 36.1, “CCB Header Format”)
 646 4              4               Command control
 647                                Bits         Field Description
 648                                [31:28]      Primary Input Format (see Section 36.2.1.1.1, “Primary Input
 649                                             Format”)
 650                                [27:23]      Primary Input Element Size (see Section 36.2.1.1.2, “Primary
 651                                             Input Element Size”)
 652                                [22:20]      Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
 653                                             Element Offsets”)
 654                                [19]         Secondary Input Format (see Section 36.2.1.1.3, “Secondary
 655                                             Input Format”)
 656                                [18:16]      Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
 657                                             Element Offsets”)
 658                                [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
 659                                             “Secondary Input Element Size”
 660                                [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
 661                                [9:5]        Operand size for first scan criteria value. In a scan value
 662                                             operation, this is one of two potential extact match values.
 663                                             In a scan range operation, this is the size of the upper range
 664
 665
 666                                                520
 667 \f                        Coprocessor services
 668
 669
 670 Offset   Size   Field Description
 671                 Bits         Field Description
 672                              boundary. The value of this field is the number of bytes in the
 673                              operand, minus 1. Values 0xF-0x1E are reserved. A value of
 674                              0x1F indicates this operand is not in use for this scan operation.
 675                 [4:0]        Operand size for second scan criteria value. In a scan value
 676                              operation, this is one of two potential extact match values.
 677                              In a scan range operation, this is the size of the lower range
 678                              boundary. The value of this field is the number of bytes in the
 679                              operand, minus 1. Values 0xF-0x1E are reserved. A value of
 680                              0x1F indicates this operand is not in use for this scan operation.
 681 8        8      Completion (same fields as Section 36.2.1.2, “Extract command”)
 682 16       8      Primary Input (same fields as Section 36.2.1.2, “Extract command”)
 683 24       8      Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
 684 32       8      Secondary Input, if used by Primary Input Format. Same fields as Primary
 685                 Input.
 686 40       4      Most significant 4 bytes of first scan criteria operand. If first operand is less
 687                 than 4 bytes, the value is left-aligned to the lowest address bytes.
 688 44       4      Most significant 4 bytes of second scan criteria operand. If second operand
 689                 is less than 4 bytes, the value is left-aligned to the lowest address bytes.
 690 48       8      Output (same fields as Primary Input)
 691 56       8      Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
 692                 “Extract command”
 693 64       4      Next 4 most significant bytes of first scan criteria operand occuring after the
 694                 bytes specified at offset 40, if needed by the operand size. If first operand
 695                 is less than 8 bytes, the valid bytes are left-aligned to the lowest address.
 696 68       4      Next 4 most significant bytes of second scan criteria operand occuring after
 697                 the bytes specified at offset 44, if needed by the operand size. If second
 698                 operand is less than 8 bytes, the valid bytes are left-aligned to the lowest
 699                 address.
 700 72       4      Next 4 most significant bytes of first scan criteria operand occuring after the
 701                 bytes specified at offset 64, if needed by the operand size. If first operand
 702                 is less than 12 bytes, the valid bytes are left-aligned to the lowest address.
 703 76       4      Next 4 most significant bytes of second scan criteria operand occuring after
 704                 the bytes specified at offset 68, if needed by the operand size. If second
 705                 operand is less than 12 bytes, the valid bytes are left-aligned to the lowest
 706                 address.
 707 80       4      Next 4 most significant bytes of first scan criteria operand occuring after the
 708                 bytes specified at offset 72, if needed by the operand size. If first operand
 709                 is less than 16 bytes, the valid bytes are left-aligned to the lowest address.
 710 84       4      Next 4 most significant bytes of second scan criteria operand occuring after
 711                 the bytes specified at offset 76, if needed by the operand size. If second
 712                 operand is less than 16 bytes, the valid bytes are left-aligned to the lowest
 713                 address.
 714
 715
 716
 717
 718                                 521
 719 \f                                               Coprocessor services
 720
 721
 722 36.2.1.4. Translate commands
 723
 724         The translate commands takes an input array of indicies, and a table of single bit values indexed by those
 725         indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in
 726         the input array. The output should therefore contain exactly one bit per index in the input data stream,
 727         when outputing as a bit vector. When outputing as an index array, the number of elements depends on the
 728         values read in the bit table, but will always be less than, or equal to, the number of input elements. Only
 729         a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP
 730         encoded input streams are allowed. The primary input data element size must be 3 bytes or less.
 731
 732         The maximum table index size allowed is 15 bits, however, larger input elements may be used to provide
 733         additional processing of the output values. If 2 or 3 byte values are used, the least significant 15 bits are
 734         used as an index into the bit table. The most significant 9 bits (when using 3-byte input elements) or single
 735         bit (when using 2-byte input elements) are compared against a fixed 9-bit test value provided in the CCB.
 736         If the values match, the value from the bit table is used as the output element value. If the values do not
 737         match, the output data element value is forced to 0.
 738
 739         In the inverted translate operation, the bit value read from bit table is inverted prior to its use. The additional
 740         additional processing based on any additional non-index bits remains unchanged, and still forces the output
 741         element value to 0 on a mismatch. The specific type of translate command is indicated by the command
 742         code in the CCB header.
 743
 744         There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
 745         0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the
 746         output format was a bit array.
 747
 748         The return value of the CCB completion area contains the number of bits set in the output bit vector,
 749         or number of elements in the output index array. The “number of elements processed” field in the CCB
 750         completion area will be valid, indicating the number of input elements processed.
 751
 752         These commands are 64-byte “short format” CCBs.
 753
 754         The translate CCB command format can be specified by the following packed C structure for a big-endian
 755         machine:
 756
 757
 758                  struct translate_ccb {
 759                         uint32_t header;
 760                         uint32_t control;
 761                         uint64_t completion;
 762                         uint64_t primary_input;
 763                         uint64_t data_access_control;
 764                         uint64_t secondary_input;
 765                         uint64_t reserved;
 766                         uint64_t output;
 767                         uint64_t table;
 768                  };
 769
 770
 771         The exact field offsets, sizes, and composition are as follows:
 772
 773
 774         Offset          Size             Field Description
 775         0               4                CCB header (Table 36.1, “CCB Header Format”)
 776
 777
 778                                                         522
 779 \f                        Coprocessor services
 780
 781
 782 Offset   Size   Field Description
 783 4        4      Command control
 784                 Bits         Field Description
 785                 [31:28]      Primary Input Format (see Section 36.2.1.1.1, “Primary Input
 786                              Format”)
 787                 [27:23]      Primary Input Element Size (see Section 36.2.1.1.2, “Primary
 788                              Input Element Size”)
 789                 [22:20]      Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
 790                              Element Offsets”)
 791                 [19]         Secondary Input Format (see Section 36.2.1.1.3, “Secondary
 792                              Input Format”)
 793                 [18:16]      Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
 794                              Element Offsets”)
 795                 [15:14]      Secondary Input Element Size (see Section 36.2.1.1.4,
 796                              “Secondary Input Element Size”
 797                 [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
 798                 [9]          Reserved
 799                 [8:0]        Test value used for comparison against the most significant bits
 800                              in the input values, when using 2 or 3 byte input elements.
 801 8        8      Completion (same fields as Section 36.2.1.2, “Extract command”
 802 16       8      Primary Input (same fields as Section 36.2.1.2, “Extract command”
 803 24       8      Data Access Control (same fields as Section 36.2.1.2, “Extract command”,
 804                 except Primary Input Length Format may not use the 0x0 value)
 805 32       8      Secondary Input, if used by Primary Input Format. Same fields as Primary
 806                 Input.
 807 40       8      Reserved
 808 48       8      Output (same fields as Primary Input)
 809 56       8      Bit Table
 810                 Bits         Field Description
 811                 [63:60]      ADI version (see Section 36.2.1.1.7, “Application Data
 812                              Integrity (ADI)”)
 813                 [59:56]      If using real address, these bits should be filled in with the
 814                              page size code for the page boundary checking the guest wants
 815                              the virtual machine to use when accessing this data stream
 816                              (checking is only guaranteed to be performed when using API
 817                              version 1.1 and later). If using a virtual address, this field will
 818                              be used as as bit table address bits [59:56]
 819                 [55:4]       Bit table address bits [55:4]. Address type is determined by
 820                              CCB header. Address must be 64-byte aligned (CCB version
 821                              0) or 16-byte aligned (CCB version 1).
 822                 [3:0]        Bit table version
 823                              Value      Description
 824                              0          4KB table size
 825                              1          8KB table size
 826
 827
 828
 829                                  523
 830 \f                                              Coprocessor services
 831
 832
 833 36.2.1.5. Select command
 834         The select command filters the primary input data stream by using a secondary input bit vector to determine
 835         which input elements to include in the output. For each bit set at a given index N within the bit vector,
 836         the Nth input element is included in the output. If the bit is not set, the element is not included. Only a
 837         restricted subset of the possible input format types are supported. No variable width or run length encoded
 838         input streams are allowed, since the secondary input stream is used for the filtering bit vector.
 839
 840         The only supported output format is a padded, byte-aligned output stream. The stream follows the same
 841         rules and restrictions as padded output stream described in Section 36.2.1.2, “Extract command”.
 842
 843         The return value of the CCB completion area contains the number of bits set in the input bit vector. The
 844         "number of elements processed" field in the CCB completion area will be valid, indicating the number
 845         of input elements processed.
 846
 847         The select CCB is a 64-byte “short format” CCB.
 848
 849         The select CCB command format can be specified by the following packed C structure for a big-endian
 850         machine:
 851
 852
 853                   struct select_ccb {
 854                          uint32_t header;
 855                          uint32_t control;
 856                          uint64_t completion;
 857                          uint64_t primary_input;
 858                          uint64_t data_access_control;
 859                          uint64_t secondary_input;
 860                          uint64_t reserved;
 861                          uint64_t output;
 862                          uint64_t table;
 863                   };
 864
 865
 866         The exact field offsets, sizes, and composition are as follows:
 867
 868          Offset        Size            Field Description
 869          0             4               CCB header (Table 36.1, “CCB Header Format”)
 870          4             4               Command control
 871                                        Bits        Field Description
 872                                        [31:28]     Primary Input Format (see Section 36.2.1.1.1, “Primary Input
 873                                                    Format”)
 874                                        [27:23]     Primary Input Element Size (see Section 36.2.1.1.2, “Primary
 875                                                    Input Element Size”)
 876                                        [22:20]     Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
 877                                                    Element Offsets”)
 878                                        [19]        Secondary Input Format (see Section 36.2.1.1.3, “Secondary
 879                                                    Input Format”)
 880                                        [18:16]     Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
 881                                                    Element Offsets”)
 882                                        [15:14]     Secondary Input Element Size (see Section 36.2.1.1.4,
 883                                                    “Secondary Input Element Size”
 884
 885
 886                                                       524
 887 \f                                               Coprocessor services
 888
 889
 890         Offset         Size            Field Description
 891                                        Bits         Field Description
 892                                        [13:10]      Output Format (see Section 36.2.1.1.6, “Output Format”)
 893                                        [9]          Padding Direction selector: A value of 1 causes padding bytes
 894                                                     to be added to the left side of output elements. A value of 0
 895                                                     causes padding bytes to be added to the right side of output
 896                                                     elements.
 897                                        [8:0]        Reserved
 898         8              8               Completion (same fields as Section 36.2.1.2, “Extract command”
 899         16             8               Primary Input (same fields as Section 36.2.1.2, “Extract command”
 900         24             8               Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
 901         32             8               Secondary Bit Vector Input. Same fields as Primary Input.
 902         40             8               Reserved
 903         48             8               Output (same fields as Primary Input)
 904         56             8               Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
 905                                        “Extract command”
 906
 907 36.2.1.6. No-op and Sync commands
 908         The no-op (no operation) command is a CCB which has no processing effect. The CCB, when processed
 909         by the virtual machine, simply updates the completion area with its execution status. The CCB may have
 910         the serial-conditional flags set in order to restrict when it executes.
 911
 912         The sync command is a variant of the no-op command which with restricted execution timing. A sync
 913         command CCB will only execute when all previous commands submitted in the same request have
 914         completed. This is stronger than the conditional flag sequencing, which is only dependent on a single
 915         previous serial CCB. While the relative ordering is guaranteed, virtual machine implementations with
 916         shared hardware resources may cause the sync command to wait for longer than the minimum required
 917         time.
 918
 919         The return value of the CCB completion area is invalid for these CCBs. The “number of elements
 920         processed” field is also invalid for these CCBs.
 921
 922         These commands are 64-byte “short format” CCBs.
 923
 924         The no-op CCB command format can be specified by the following packed C structure for a big-endian
 925         machine:
 926
 927
 928                  struct nop_ccb {
 929                         uint32_t header;
 930                         uint32_t control;
 931                         uint64_t completion;
 932                         uint64_t reserved[6];
 933                  };
 934
 935
 936         The exact field offsets, sizes, and composition are as follows:
 937
 938         Offset         Size            Field Description
 939         0              4               CCB header (Table 36.1, “CCB Header Format”)
 940
 941
 942                                                        525
 943 \f                                          Coprocessor services
 944
 945
 946        Offset        Size          Field Description
 947        4             4             Command control
 948                                    Bits        Field Description
 949                                    [31]        If set, this CCB functions as a Sync command. If clear, this
 950                                                CCB functions as a No-op command.
 951                                    [30:0]      Reserved
 952        8             8             Completion (same fields as Section 36.2.1.2, “Extract command”
 953        16            46            Reserved
 954
 955 36.2.2. CCB Completion Area
 956        All CCB commands use a common 128-byte Completion Area format, which can be specified by the
 957        following packed C structure for a big-endian machine:
 958
 959
 960                 struct completion_area {
 961                        uint8_t status_flag;
 962                        uint8_t error_note;
 963                        uint8_t rsvd0[2];
 964                        uint32_t error_values;
 965                        uint32_t output_size;
 966                        uint32_t rsvd1;
 967                        uint64_t run_time;
 968                        uint64_t run_stats;
 969                        uint32_t elements;
 970                        uint8_t rsvd2[20];
 971                        uint64_t return_value;
 972                        uint64_t extra_return_value[8];
 973                 };
 974
 975
 976        The Completion Area must be a 128-byte aligned memory location. The exact layout can be described
 977        using byte offsets and sizes relative to the memory base:
 978
 979        Offset        Size          Field Description
 980        0             1             CCB execution status
 981                                    0x0                  Command not yet completed
 982                                    0x1                  Command ran and succeeded
 983                                    0x2                  Command ran and failed (partial results may be been
 984                                                         produced)
 985                                    0x3                  Command ran and was killed (partial execution may
 986                                                         have occurred)
 987                                    0x4                  Command was not run
 988                                    0x5-0xF              Reserved
 989        1             1             Error reason code
 990                                    0x0                  Reserved
 991                                    0x1                  Buffer overflow
 992
 993
 994                                                   526
 995 \f                                      Coprocessor services
 996
 997
 998 Offset          Size           Field Description
 999                                 0x2                 CCB decoding error
1000                                 0x3                 Page overflow
1001                                 0x4-0x6             Reserved
1002                                 0x7                 Command was killed
1003                                 0x8                 Command execution timeout
1004                                 0x9                 ADI miscompare error
1005                                 0xA                 Data format error
1006                                 0xB-0xD             Reserved
1007                                 0xE                 Unexpected hardware error (Do not retry)
1008                                 0xF                 Unexpected hardware error (Retry is ok)
1009                                 0x10-0x7F           Reserved
1010                                 0x80                Partial Symbol Warning
1011                                 0x81-0xFF           Reserved
1012 2               2              Reserved
1013 4               4              If a partial symbol warning was generated, this field contains the number
1014                                of remaining bits which were not decoded.
1015 8               4              Number of bytes of output produced
1016 12              4              Reserved
1017 16              8              Runtime of command (unspecified time units)
1018 24              8              Reserved
1019 32              4              Number of elements processed
1020 36              20             Reserved
1021 56              8              Return value
1022 64              64             Extended return value
1023
1024 The CCB completion area should be treated as read-only by guest software. The CCB execution status
1025 byte will be cleared by the Hypervisor to reflect the pending execution status when the CCB is submitted
1026 successfully. All other fields are considered invalid upon CCB submission until the CCB execution status
1027 byte becomes non-zero.
1028
1029 CCBs which complete with status 0x2 or 0x3 may produce partial results and/or side effects due to partial
1030 execution of the CCB command. Some valid data may be accessible depending on the fault type, however,
1031 it is recommended that guest software treat the destination buffer as being in an unknown state. If a CCB
1032 completes with a status byte of 0x2, the error reason code byte can be read to determine what corrective
1033 action should be taken.
1034
1035 A buffer overflow indicates that the results of the operation exceeded the size of the output buffer indicated
1036 in the CCB. The operation can be retried by resubmitting the CCB with a larger output buffer.
1037
1038 A CCB decoding error indicates that the CCB contained some invalid field values. It may be also be
1039 triggered if the CCB output is directed at a non-existent secondary input and the pipelining hint is followed.
1040
1041 A page overflow error indicates that the operation required accessing a memory location beyond the page
1042 size associated with a given address. No data will have been read or written past the page boundary, but
1043 partial results may have been written to the destination buffer. The CCB can be resubmitted with a larger
1044 page size memory allocation to complete the operation.
1045
1046
1047                                               527
1048 \f                                            Coprocessor services
1049
1050
1051        In the case of pipelined CCBs, a page overflow error will be triggered if the output from the pipeline source
1052        CCB ends before the input of the pipeline target CCB. Page boundaries are ignored when the pipeline
1053        hint is followed.
1054
1055        Command kill indicates that the CCB execution was halted or prevented by use of the ccb_kill API call.
1056
1057        Command timeout indicates that the CCB execution began, but did not complete within a pre-determined
1058        limit set by the virtual machine. The command may have produced some or no output. The CCB may be
1059        resubmitted with no alterations.
1060
1061        ADI miscompare indicates that the memory buffer version specified in the CCB did not match the value
1062        in memory when accessed by the virtual machine. Guest software should not attempt to resubmit the CCB
1063        without determining the cause of the version mismatch.
1064
1065        A data format error indicates that the input data stream did not follow the specified data input formatting
1066        selected in the CCB.
1067
1068        Some CCBs which encounter hardware errors may be resubmitted without change. Persistent hardware
1069        errors may result in multiple failures until RAS software can identify and isolate the faulty component.
1070
1071        The output size field indicates the number of bytes of valid output in the destination buffer. This field is
1072        not valid for all possible CCB commands.
1073
1074        The runtime field indicates the execution time of the CCB command once it leaves the internal virtual
1075        machine queue. The time units are fixed, but unspecified, allowing only relative timing comparisons
1076        by guest software. The time units may also vary by hardware platform, and should not be construed to
1077        represent any absolute time value.
1078
1079        Some data query commands process data in units of elements. If applicable to the command, the number of
1080        elements processed is indicated in the listed field. This field is not valid for all possible CCB commands.
1081
1082        The return value and extended return value fields are output locations for commands which do not use
1083        a destination output buffer, or have secondary return results. The field is not valid for all possible CCB
1084        commands.
1085
1086 36.3. Hypervisor API Functions
1087 36.3.1. ccb_submit
1088        trap#             FAST_TRAP
1089        function#         CCB_SUBMIT
1090        arg0              address
1091        arg1              length
1092        arg2              flags
1093        arg3              reserved
1094        ret0              status
1095        ret1              length
1096        ret2              status data
1097        ret3              reserved
1098
1099        Submit one or more coprocessor control blocks (CCBs) for evaluation and processing by the virtual
1100        machine. The CCBs are passed in a linear array indicated by address. length indicates the size of
1101        the array in bytes.
1102
1103
1104                                                      528
1105 \f                                      Coprocessor services
1106
1107
1108 The address should be aligned to the size indicated by length, rounded up to the nearest power of
1109 two. Virtual machines implementations may reject submissions which do not adhere to that alignment.
1110 length must be a multiple of 64 bytes. If length is zero, the maximum supported array length will be
1111 returned as length in ret1. In all other cases, the length value in ret1 will reflect the number of bytes
1112 successfully consumed from the input CCB array.
1113
1114       Implementation note
1115       Virtual machines should never reject submissions based on the alignment of address if the
1116       entire array is contained within a single memory page of the smallest page size supported by the
1117       virtual machine.
1118
1119 A guest may choose to submit addresses used in this API function, including the CCB array address,
1120 as either a real or virtual addresses, with the type of each address indicated in flags. Virtual addresses
1121 must be present in either the TLB or an active TSB to be processed. The translation context for virtual
1122 addresses is determined by a combination of CCB contents and the flags argument.
1123
1124 The flags argument is divided into multiple fields defined as follows:
1125
1126
1127 Bits            Field Description
1128 [63:16]         Reserved
1129 [15]            Disable ADI for VA reads (in API 2.0)
1130                 Reserved (in API 1.0)
1131 [14]            Virtual addresses within CCBs are translated in privileged context
1132 [13:12]         Alternate translation context for virtual addresses within CCBs:
1133                  0b'00        CCBs requesting alternate context are rejected
1134                  0b'01        Reserved
1135                  0b'10        CCBs requesting alternate context use secondary context
1136                  0b'11        CCBs requesting alternate context use nucleus context
1137 [11:9]          Reserved
1138 [8]             Queue info flag
1139 [7]             All-or-nothing flag
1140 [6]             If address is a virtual address, treat its translation context as privileged
1141 [5:4]           Address type of address:
1142                  0b'00        Real address
1143                  0b'01        Virtual address in primary context
1144                  0b'10        Virtual address in secondary context
1145                  0b'11        Virtual address in nucleus context
1146 [3:2]           Reserved
1147 [1:0]           CCB command type:
1148                  0b'00        Reserved
1149                  0b'01        Reserved
1150                  0b'10        Query command
1151                  0b'11        Reserved
1152
1153
1154
1155                                               529
1156 \f                                             Coprocessor services
1157
1158
1159          The CCB submission type and address type for the CCB array must be provided in the flags argument.
1160          All other fields are optional values which change the default behavior of the CCB processing.
1161
1162          When set to one, the "Disable ADI for VA reads" bit will turn off ADI checking when using a virtual
1163          address to load data. ADI checking will still be done when loading real-addressed memory. This bit is only
1164          available when using major version 2 of the coprocessor API group; at major version 1 it is reserved. For
1165          more information about using ADI and DAX, see Section 36.2.1.1.7, “Application Data Integrity (ADI)”.
1166
1167          By default, all virtual addresses are treated as user addresses. If the virtual address translations are
1168          privileged, they must be marked as such in the appropriate flags field. The virtual addresses used within
1169          the submitted CCBs must all be translated with the same privilege level.
1170
1171          By default, all virtual addresses used within the submitted CCBs are translated using the primary context
1172          active at the time of the submission. The address type field within a CCB allows each address to request
1173          translation in an alternate address context. The address context used when the alternate address context is
1174          requested is selected in the flags argument.
1175
1176          The all-or-nothing flag specifies whether the virtual machine should allow partial submissions of the
1177          input CCB array. When using CCBs with serial-conditional flags, it is strongly recommended to use
1178          the all-or-nothing flag to avoid broken conditional chains. Using long CCB chains on a machine under
1179          high coprocessor load may make this impractical, however, and require submitting without the flag.
1180          When submitting serial-conditional CCBs without the all-or-nothing flag, guest software must manually
1181          implement the serial-conditional behavior at any point where the chain was not submitted in a single API
1182          call, and resubmission of the remaining CCBs should clear any conditional flag that might be set in the
1183          first remaining CCB. Failure to do so will produce indeterminate CCB execution status and ordering.
1184
1185          When the all-or-nothing flag is not specified, callers should check the value of length in ret1 to determine
1186          how many CCBs from the array were successfully submitted. Any remaining CCBs can be resubmitted
1187          without modifications.
1188
1189          The value of length in ret1 is also valid when the API call returns an error, and callers should always
1190          check its value to determine which CCBs in the array were already processed. This will additionally
1191          identify which CCB encountered the processing error, and was not submitted successfully.
1192
1193          If the queue info flag is used during submission, and at least one CCB was successfully submitted, the
1194          length value in ret1 will be a multi-field value defined as follows:
1195           Bits          Field Description
1196           [63:48]       DAX unit instance identifier
1197           [47:32]       DAX queue instance identifier
1198           [31:16]       Reserved
1199           [15:0]        Number of CCB bytes successfully submitted
1200
1201          The value of status data depends on the status value. See error status code descriptions for details.
1202          The value is undefined for status values that do not specifically list a value for the status data.
1203
1204          The API has a reserved input and output register which will be used in subsequent minor versions of this
1205          API function. Guest software implementations should treat that register as voltile across the function call
1206          in order to maintain forward compatibility.
1207
1208 36.3.1.1. Errors
1209           EOK                       One or more CCBs have been accepted and enqueued in the virtual machine
1210                                     and no errors were been encountered during submission. Some submitted
1211                                     CCBs may not have been enqueued due to internal virtual machine limitations,
1212                                     and may be resubmitted without changes.
1213
1214
1215                                                        530
1216 \f                        Coprocessor services
1217
1218
1219 EWOULDBLOCK    An internal resource conflict within the virtual machine has prevented it from
1220                being able to complete the CCB submissions sufficiently quickly, requiring
1221                it to abandon processing before it was complete. Some CCBs may have been
1222                successfully enqueued prior to the block, and all remaining CCBs may be
1223                resubmitted without changes.
1224 EBADALIGN      CCB array is not on a 64-byte boundary, or the array length is not a multiple
1225                of 64 bytes.
1226 ENORADDR       A real address used either for the CCB array, or within one of the submitted
1227                CCBs, is not valid for the guest. Some CCBs may have been enqueued prior
1228                to the error being detected.
1229 ENOMAP         A virtual address used either for the CCB array, or within one of the submitted
1230                CCBs, could not be translated by the virtual machine using either the TLB
1231                or TSB contents. The submission may be retried after adding the required
1232                mapping, or by converting the virtual address into a real address. Due to the
1233                shared nature of address translation resources, there is no theoretical limit on
1234                the number of times the translation may fail, and it is recommended all guests
1235                implement some real address based backup. The virtual address which failed
1236                translation is returned as status data in ret2. Some CCBs may have been
1237                enqueued prior to the error being detected.
1238 EINVAL         The virtual machine detected an invalid CCB during submission, or invalid
1239                input arguments, such as bad flag values. Note that not all invalid CCB values
1240                will be detected during submission, and some may be reported as errors in the
1241                completion area instead. Some CCBs may have been enqueued prior to the
1242                error being detected. This error may be returned if the CCB version is invalid.
1243 ETOOMANY       The request was submitted with the all-or-nothing flag set, and the array size is
1244                greater than the virtual machine can support in a single request. The maximum
1245                supported size for the current virtual machine can be queried by submitting a
1246                request with a zero length array, as described above.
1247 ENOACCESS      The guest does not have permission to submit CCBs, or an address used in a
1248                CCBs lacks sufficient permissions to perform the required operation (no write
1249                permission on the destination buffer address, for example). A virtual address
1250                which fails permission checking is returned as status data in ret2. Some
1251                CCBs may have been enqueued prior to the error being detected.
1252 EUNAVAILABLE   The requested CCB operation could not be performed at this time. The
1253                restricted operation availability may apply only to the first unsuccessfully
1254                submitted CCB, or may apply to a larger scope. The status should not be
1255                interpreted as permanent, and the guest should attempt to submit CCBs in
1256                the future which had previously been unable to be performed. The status
1257                data provides additional information about scope of the retricted availability
1258                as follows:
1259                Value       Description
1260                0           Processing for the exact CCB instance submitted was unavailable,
1261                            and it is recommended the guest emulate the operation. The
1262                            guest should continue to submit all other CCBs, and assume no
1263                            restrictions beyond this exact CCB instance.
1264                1           Processing is unavailable for all CCBs using the requested opcode,
1265                            and it is recommended the guest emulate the operation. The
1266                            guest should continue to submit all other CCBs that use different
1267                            opcodes, but can expect continued rejections of CCBs using the
1268                            same opcode in the near future.
1269
1270
1271                                  531
1272 \f                                              Coprocessor services
1273
1274
1275                                       Value     Description
1276                                       2         Processing is unavailable for all CCBs using the requested CCB
1277                                                 version, and it is recommended the guest emulate the operation.
1278                                                 The guest should continue to submit all other CCBs that use
1279                                                 different CCB versions, but can expect continued rejections of
1280                                                 CCBs using the same CCB version in the near future.
1281                                       3         Processing is unavailable for all CCBs on the submitting vcpu,
1282                                                 and it is recommended the guest emulate the operation or resubmit
1283                                                 the CCB on a different vcpu. The guest should continue to submit
1284                                                 CCBs on all other vcpus but can expect continued rejections of all
1285                                                 CCBs on this vcpu in the near future.
1286                                       4         Processing is unavailable for all CCBs, and it is recommended
1287                                                 the guest emulate the operation. The guest should expect all CCB
1288                                                 submissions to be similarly rejected in the near future.
1289
1290
1291 36.3.2. ccb_info
1292
1293         trap#               FAST_TRAP
1294         function#           CCB_INFO
1295         arg0                address
1296         ret0                status
1297         ret1                CCB state
1298         ret2                position
1299         ret3                dax
1300         ret4                queue
1301
1302        Requests status information on a previously submitted CCB. The previously submitted CCB is identified
1303        by the 64-byte aligned real address of the CCBs completion area.
1304
1305        A CCB can be in one of 4 states:
1306
1307
1308         State                     Value       Description
1309         COMPLETED                 0           The CCB has been fetched and executed, and is no longer active in
1310                                               the virtual machine.
1311         ENQUEUED                  1           The requested CCB is current in a queue awaiting execution.
1312         INPROGRESS                2           The CCB has been fetched and is currently being executed. It may still
1313                                               be possible to stop the execution using the ccb_kill hypercall.
1314         NOTFOUND                  3           The CCB could not be located in the virtual machine, and does not
1315                                               appear to have been executed. This may occur if the CCB was lost
1316                                               due to a hardware error, or the CCB may not have been successfully
1317                                               submitted to the virtual machine in the first place.
1318
1319                Implementation note
1320                Some platforms may not be able to report CCBs that are currently being processed, and therefore
1321                guest software should invoke the ccb_kill hypercall prior to assuming the request CCB will never
1322                be executed because it was in the NOTFOUND state.
1323
1324
1325                                                        532
1326 \f                                             Coprocessor services
1327
1328
1329          The position return value is only valid when the state is ENQUEUED. The value returned is the number
1330          of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute.
1331
1332          The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit
1333          instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value
1334          matches the value that would have been, or was, returned by ccb_submit using the queue info flag.
1335
1336          The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX
1337          queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The
1338          value matches the value that would have been, or was, returned by ccb_submit using the queue info flag.
1339
1340 36.3.2.1. Errors
1341
1342           EOK                       The request was proccessed and the CCB state is valid.
1343           EBADALIGN                 address is not on a 64-byte aligned.
1344           ENORADDR                  The real address provided for address is not valid.
1345           EINVAL                    The CCB completion area contents are not valid.
1346           EWOULDBLOCK               Internal resource contraints prevented the CCB state from being queried at this
1347                                     time. The guest should retry the request.
1348           ENOACCESS                 The guest does not have permission to access the coprocessor virtual device
1349                                     functionality.
1350
1351 36.3.3. ccb_kill
1352
1353           trap#           FAST_TRAP
1354           function#       CCB_KILL
1355           arg0            address
1356           ret0            status
1357           ret1            result
1358
1359          Request to stop execution of a previously submitted CCB. The previously submitted CCB is identified by
1360          the 64-byte aligned real address of the CCBs completion area.
1361
1362          The kill attempt can produce one of several values in the result return value, reflecting the CCB state
1363          and actions taken by the Hypervisor:
1364
1365           Result                Value       Description
1366           COMPLETED             0           The CCB has been fetched and executed, and is no longer active in
1367                                             the virtual machine. It could not be killed and no action was taken.
1368           DEQUEUED              1           The requested CCB was still enqueued when the kill request was
1369                                             submitted, and has been removed from the queue. Since the CCB
1370                                             never began execution, no memory modifications were produced by
1371                                             it, and the completion area will never be updated. The same CCB may
1372                                             be submitted again, if desired, with no modifications required.
1373           KILLED                2           The CCB had been fetched and was being executed when the kill
1374                                             request was submitted. The CCB execution was stopped, and the CCB
1375                                             is no longer active in the virtual machine. The CCB completion area
1376                                             will reflect the killed status, with the subsequent implications that
1377                                             partial results may have been produced. Partial results may include full
1378
1379
1380                                                       533
1381 \f                                              Coprocessor services
1382
1383
1384           Result                 Value       Description
1385                                              command execution if the command was stopped just prior to writing
1386                                              to the completion area.
1387           NOTFOUND               3           The CCB could not be located in the virtual machine, and does not
1388                                              appear to have been executed. This may occur if the CCB was lost
1389                                              due to a hardware error, or the CCB may not have been successfully
1390                                              submitted to the virtual machine in the first place. CCBs in the state
1391                                              are guaranteed to never execute in the future unless resubmitted.
1392
1393 36.3.3.1. Interactions with Pipelined CCBs
1394
1395          If the pipeline target CCB is killed but the pipeline source CCB was skipped, the completion area of the
1396          target CCB may contain status (4,0) "Command was skipped" instead of (3,7) "Command was killed".
1397
1398          If the pipeline source CCB is killed, the pipeline target CCB's completion status may read (1,0) "Success".
1399          This does not mean the target CCB was processed; since the source CCB was killed, there was no
1400          meaningful output on which the target CCB could operate.
1401
1402 36.3.3.2. Errors
1403
1404           EOK                        The request was proccessed and the result is valid.
1405           EBADALIGN                  address is not on a 64-byte aligned.
1406           ENORADDR                   The real address provided for address is not valid.
1407           EINVAL                     The CCB completion area contents are not valid.
1408           EWOULDBLOCK                Internal resource contraints prevented the CCB from being killed at this time.
1409                                      The guest should retry the request.
1410           ENOACCESS                  The guest does not have permission to access the coprocessor virtual device
1411                                      functionality.
1412
1413 36.3.4. dax_info
1414           trap#            FAST_TRAP
1415           function#        DAX_INFO
1416           ret0             status
1417           ret1             Number of enabled DAX units
1418           ret2             Number of disabled DAX units
1419
1420          Returns the number of DAX units that are enabled for the calling guest to submit CCBs. The number of
1421          DAX units that are disabled for the calling guest are also returned. A disabled DAX unit would have been
1422          available for CCB submission to the calling guest had it not been offlined.
1423
1424 36.3.4.1. Errors
1425
1426           EOK                        The request was proccessed and the number of enabled/disabled DAX units
1427                                      are valid.
1428
1429
1430
1431
1432                                                        534
1433 \f