1Excerpt from UltraSPARC Virtual Machine Specification 2Compiled from version 3.0.20+15 3Publication date 2017-09-25 08:21 4Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved. 5Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf" 6Authors: 7 Charles Kunzman 8 Sam Glidden 9 Mark Cianchetti 10 11 12Chapter 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 1836.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 compatibility 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 availability 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 4836.1.1. DAX Compatibility Property 49 The query functionality may vary based on the compatibility property of the virtual device: 50 5136.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 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 8136.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 8536.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 11136.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 12236.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 Coprocessor services 129 130 131referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed 132via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not 133guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB 134execution. 135 136All CCBs begin with a common 32-bit header. 137 138Table 36.1. CCB Header Format 139Bits 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 Coprocessor services 177 178 179Bits 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 203The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes 204and 1 for 128 bytes. 205 206The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial 207flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same 208CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs 209with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the 210previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs 211to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag. 212A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional 213and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs 214execute in parallel based on the completion of another CCB. 215 216The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to 217the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from 218memory. The Pipeline flag is advisory and may be dropped. 219 220Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the 221target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs 222is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB 223with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional 224bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit. 225 226 227 512 228 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 24336.2.1. Query CCB Command Formats 24436.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 25036.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 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 30136.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 30736.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 evaluates to 1, 1 evaluates 317 to 2, etc) 318 1 Element is stored as value 319 32036.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 33136.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 Coprocessor services 343 344 34536.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 37136.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 38636.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 Coprocessor services 398 399 40036.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 Coprocessor services 455 456 457Offset 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 4678 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. 47916 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. 49124 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 Coprocessor services 505 506 507Offset 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 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 59036.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 Coprocessor services 610 611 612entry is the index of an input element that matched the scan criteria. An inverted scan command produces 613a similar array, but of all the input elements which did NOT match the scan criteria. 614 615The return value of the CCB completion area contains the number of input elements found which match 616the scan criteria (or number that did not match for the inverted scans). The “number of elements processed” 617field in the CCB completion area will be valid, indicating the number of input elements processed. 618 619These commands are 128-byte “long format” CCBs. 620 621The scan CCB command format can be specified by the following packed C structure for a big-endian 622machine: 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 642The exact field offsets, sizes, and composition are as follows: 643 644Offset Size Field Description 6450 4 CCB header (Table 36.1, “CCB Header Format”) 6464 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 exact match values. 663 In a scan range operation, this is the size of the upper range 664 665 666 520 667 Coprocessor services 668 669 670Offset 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 exact 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. 6818 8 Completion (same fields as Section 36.2.1.2, “Extract command”) 68216 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”) 68324 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”) 68432 8 Secondary Input, if used by Primary Input Format. Same fields as Primary 685 Input. 68640 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. 68844 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. 69048 8 Output (same fields as Primary Input) 69156 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, 692 “Extract command” 69364 4 Next 4 most significant bytes of first scan criteria operand occurring 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. 69668 4 Next 4 most significant bytes of second scan criteria operand occurring 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. 70072 4 Next 4 most significant bytes of first scan criteria operand occurring 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. 70376 4 Next 4 most significant bytes of second scan criteria operand occurring 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. 70780 4 Next 4 most significant bytes of first scan criteria operand occurring 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. 71084 4 Next 4 most significant bytes of second scan criteria operand occurring 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 Coprocessor services 720 721 72236.2.1.4. Translate commands 723 724 The translate commands takes an input array of indices, and a table of single bit values indexed by those 725 indices, 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 outputting as a bit vector. When outputting 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 indices 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 Coprocessor services 780 781 782Offset Size Field Description 7834 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. 8018 8 Completion (same fields as Section 36.2.1.2, “Extract command” 80216 8 Primary Input (same fields as Section 36.2.1.2, “Extract command” 80324 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) 80532 8 Secondary Input, if used by Primary Input Format. Same fields as Primary 806 Input. 80740 8 Reserved 80848 8 Output (same fields as Primary Input) 80956 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 Coprocessor services 831 832 83336.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 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 90736.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 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 95536.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 Coprocessor services 996 997 998Offset 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 10122 2 Reserved 10134 4 If a partial symbol warning was generated, this field contains the number 1014 of remaining bits which were not decoded. 10158 4 Number of bytes of output produced 101612 4 Reserved 101716 8 Runtime of command (unspecified time units) 101824 8 Reserved 101932 4 Number of elements processed 102036 20 Reserved 102156 8 Return value 102264 64 Extended return value 1023 1024The CCB completion area should be treated as read-only by guest software. The CCB execution status 1025byte will be cleared by the Hypervisor to reflect the pending execution status when the CCB is submitted 1026successfully. All other fields are considered invalid upon CCB submission until the CCB execution status 1027byte becomes non-zero. 1028 1029CCBs which complete with status 0x2 or 0x3 may produce partial results and/or side effects due to partial 1030execution of the CCB command. Some valid data may be accessible depending on the fault type, however, 1031it is recommended that guest software treat the destination buffer as being in an unknown state. If a CCB 1032completes with a status byte of 0x2, the error reason code byte can be read to determine what corrective 1033action should be taken. 1034 1035A buffer overflow indicates that the results of the operation exceeded the size of the output buffer indicated 1036in the CCB. The operation can be retried by resubmitting the CCB with a larger output buffer. 1037 1038A CCB decoding error indicates that the CCB contained some invalid field values. It may be also be 1039triggered if the CCB output is directed at a non-existent secondary input and the pipelining hint is followed. 1040 1041A page overflow error indicates that the operation required accessing a memory location beyond the page 1042size associated with a given address. No data will have been read or written past the page boundary, but 1043partial results may have been written to the destination buffer. The CCB can be resubmitted with a larger 1044page size memory allocation to complete the operation. 1045 1046 1047 527 1048 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 108636.3. Hypervisor API Functions 108736.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 Coprocessor services 1106 1107 1108The address should be aligned to the size indicated by length, rounded up to the nearest power of 1109two. Virtual machines implementations may reject submissions which do not adhere to that alignment. 1110length must be a multiple of 64 bytes. If length is zero, the maximum supported array length will be 1111returned as length in ret1. In all other cases, the length value in ret1 will reflect the number of bytes 1112successfully 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 1119A guest may choose to submit addresses used in this API function, including the CCB array address, 1120as either a real or virtual addresses, with the type of each address indicated in flags. Virtual addresses 1121must be present in either the TLB or an active TSB to be processed. The translation context for virtual 1122addresses is determined by a combination of CCB contents and the flags argument. 1123 1124The flags argument is divided into multiple fields defined as follows: 1125 1126 1127Bits 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 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 120836.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 Coprocessor services 1217 1218 1219EWOULDBLOCK 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. 1224EBADALIGN CCB array is not on a 64-byte boundary, or the array length is not a multiple 1225 of 64 bytes. 1226ENORADDR 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. 1229ENOMAP 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. 1238EINVAL 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. 1243ETOOMANY 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. 1247ENOACCESS 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. 1252EUNAVAILABLE 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 restricted 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 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 129136.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 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 identifier 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 identifier 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 134036.3.2.1. Errors 1341 1342 EOK The request was processed 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 constraints 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 135136.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 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 139336.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 140236.3.3.2. Errors 1403 1404 EOK The request was processed 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 constraints 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 141336.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 142436.3.4.1. Errors 1425 1426 EOK The request was processed and the number of enabled/disabled DAX units 1427 are valid. 1428 1429 1430 1431 1432 534 1433 1434