0001 Excerpt from UltraSPARC Virtual Machine Specification
0002 Compiled from version 3.0.20+15
0003 Publication date 2017-09-25 08:21
0004 Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved.
0005 Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf"
0006 Authors:
0007 Charles Kunzman
0008 Sam Glidden
0009 Mark Cianchetti
0010
0011
0012 Chapter 36. Coprocessor services
0013 The following APIs provide access via the Hypervisor to hardware assisted data processing functionality.
0014 These APIs may only be provided by certain platforms, and may not be available to all virtual machines
0015 even on supported platforms. Restrictions on the use of these APIs may be imposed in order to support
0016 live-migration and other system management activities.
0017
0018 36.1. Data Analytics Accelerator
0019 The Data Analytics Accelerator (DAX) functionality is a collection of hardware coprocessors that provide
0020 high speed processoring of database-centric operations. The coprocessors may support one or more of
0021 the following data query operations: search, extraction, compression, decompression, and translation. The
0022 functionality offered may vary by virtual machine implementation.
0023
0024 The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device
0025 compatibilty property. Functionality is accessed through the submission of Command Control Blocks
0026 (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status
0027 of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a
0028 separate Completion Area and, unless execution order is specifically restricted through the use of serial-
0029 conditional flags, the execution order of submitted CCBs is arbitrary. Likewise, the time to completion
0030 for a given CCB is never guaranteed.
0031
0032 Guest software may implement a software timeout on CCB operations, and if the timeout is exceeded, the
0033 operation may be cancelled or killed via the ccb_kill API function. It is recommended for guest software
0034 to implement a software timeout to account for certain RAS errors which may result in lost CCBs. It is
0035 recommended such implementation use the ccb_info API function to check the status of a CCB prior to
0036 killing it in order to determine if the CCB is still in queue, or may have been lost due to a RAS error.
0037
0038 There is no fixed limit on the number of outstanding CCBs guest software may have queued in the virtual
0039 machine, however, internal resource limitations within the virtual machine can cause CCB submissions
0040 to be temporarily rejected with EWOULDBLOCK. In such cases, guests should continue to attempt
0041 submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would
0042 not be a guarantee that a future submission would succeed.
0043
0044 The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual
0045 device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device
0046 node”).
0047
0048 36.1.1. DAX Compatibility Property
0049 The query functionality may vary based on the compatibility property of the virtual device:
0050
0051 36.1.1.1. "ORCL,sun4v-dax" Device Compatibility
0052 Available CCB commands:
0053
0054 • No-op/Sync
0055
0056 • Extract
0057
0058 • Scan Value
0059
0060 • Inverted Scan Value
0061
0062 • Scan Range
0063
0064
0065 509
0066 Coprocessor services
0067
0068
0069 • Inverted Scan Range
0070
0071 • Translate
0072
0073 • Inverted Translate
0074
0075 • Select
0076
0077 See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.
0078
0079 Only version 0 CCBs are available.
0080
0081 36.1.1.2. "ORCL,sun4v-dax-fc" Device Compatibility
0082 "ORCL,sun4v-dax-fc" is compatible with the "ORCL,sun4v-dax" interface, and includes additional CCB
0083 bit fields and controls.
0084
0085 36.1.1.3. "ORCL,sun4v-dax2" Device Compatibility
0086 Available CCB commands:
0087
0088 • No-op/Sync
0089
0090 • Extract
0091
0092 • Scan Value
0093
0094 • Inverted Scan Value
0095
0096 • Scan Range
0097
0098 • Inverted Scan Range
0099
0100 • Translate
0101
0102 • Inverted Translate
0103
0104 • Select
0105
0106 See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats.
0107
0108 Version 0 and 1 CCBs are available. Only version 0 CCBs may use Huffman encoded data, whereas only
0109 version 1 CCBs may use OZIP.
0110
0111 36.1.2. DAX Virtual Device Interrupts
0112 The DAX virtual device has multiple interrupts associated with it which may be used by the guest if
0113 desired. The number of device interrupts available to the guest is indicated in the virtual device node of the
0114 guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). If the device
0115 node indicates N interrupts available, the guest may use any value from 0 to N - 1 (inclusive) in a CCB
0116 interrupt number field. Using values outside this range will result in the CCB being rejected for an invalid
0117 field value.
0118
0119 The interrupts may be bound and managed using the standard sun4v device interrupts API (Chapter 16,
0120 Device interrupt services). Sysino interrupts are not available for DAX devices.
0121
0122 36.2. Coprocessor Control Block (CCB)
0123 CCBs are either 64 or 128 bytes long, depending on the operation type. The exact contents of the CCB
0124 are command specific, but all CCBs contain at least one memory buffer address. All memory locations
0125
0126
0127 510
0128 Coprocessor services
0129
0130
0131 referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed
0132 via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not
0133 guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB
0134 execution.
0135
0136 All CCBs begin with a common 32-bit header.
0137
0138 Table 36.1. CCB Header Format
0139 Bits Field Description
0140 [31:28] CCB version. For API version 2.0: set to 1 if CCB uses OZIP encoding; set to 0 if the CCB
0141 uses Huffman encoding; otherwise either 0 or 1. For API version 1.0: always set to 0.
0142 [27] When API version 2.0 is negotiated, this is the Pipeline Flag [512]. It is reserved in
0143 API version 1.0
0144 [26] Long CCB flag [512]
0145 [25] Conditional synchronization flag [512]
0146 [24] Serial synchronization flag
0147 [23:16] CCB operation code:
0148 0x00 No Operation (No-op) or Sync
0149 0x01 Extract
0150 0x02 Scan Value
0151 0x12 Inverted Scan Value
0152 0x03 Scan Range
0153 0x13 Inverted Scan Range
0154 0x04 Translate
0155 0x14 Inverted Translate
0156 0x05 Select
0157 [15:13] Reserved
0158 [12:11] Table address type
0159 0b'00 No address
0160 0b'01 Alternate context virtual address
0161 0b'10 Real address
0162 0b'11 Primary context virtual address
0163 [10:8] Output/Destination address type
0164 0b'000 No address
0165 0b'001 Alternate context virtual address
0166 0b'010 Real address
0167 0b'011 Primary context virtual address
0168 0b'100 Reserved
0169 0b'101 Reserved
0170 0b'110 Reserved
0171 0b'111 Reserved
0172 [7:5] Secondary source address type
0173
0174
0175 511
0176 Coprocessor services
0177
0178
0179 Bits Field Description
0180 0b'000 No address
0181 0b'001 Alternate context virtual address
0182 0b'010 Real address
0183 0b'011 Primary context virtual address
0184 0b'100 Reserved
0185 0b'101 Reserved
0186 0b'110 Reserved
0187 0b'111 Reserved
0188 [4:2] Primary source address type
0189 0b'000 No address
0190 0b'001 Alternate context virtual address
0191 0b'010 Real address
0192 0b'011 Primary context virtual address
0193 0b'100 Reserved
0194 0b'101 Reserved
0195 0b'110 Reserved
0196 0b'111 Reserved
0197 [1:0] Completion area address type
0198 0b'00 No address
0199 0b'01 Alternate context virtual address
0200 0b'10 Real address
0201 0b'11 Primary context virtual address
0202
0203 The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes
0204 and 1 for 128 bytes.
0205
0206 The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial
0207 flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same
0208 CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs
0209 with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the
0210 previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs
0211 to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag.
0212 A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional
0213 and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs
0214 execute in parallel based on the completion of another CCB.
0215
0216 The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to
0217 the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from
0218 memory. The Pipeline flag is advisory and may be dropped.
0219
0220 Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the
0221 target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs
0222 is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB
0223 with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional
0224 bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit.
0225
0226
0227 512
0228 Coprocessor services
0229
0230
0231 The input of the target CCB must start within 64 bytes of the output of the source CCB or the pipeline flag
0232 will be ignored. All CCBs in a pipeline must be submitted in the same call to ccb_submit.
0233
0234 The various address type fields indicate how the various address values used in the CCB should be
0235 interpreted by the virtual machine. Not all of the types specified are used by every CCB format. Types
0236 which are not applicable to the given CCB command should be indicated as type 0 (No address). Virtual
0237 addresses used in the CCB must have translation entries present in either the TLB or a configured TSB
0238 for the submitting virtual processor. Virtual addresses which cannot be translated by the virtual machine
0239 will result in the CCB submission being rejected, with the causal virtual address indicated. The CCB
0240 may be resubmitted after inserting the translation, or the address may be translated by guest software and
0241 resubmitted using the real address translation.
0242
0243 36.2.1. Query CCB Command Formats
0244 36.2.1.1. Supported Data Formats, Elements Sizes and Offsets
0245 Data for query commands may be encoded in multiple possible formats. The data query commands use a
0246 common set of values to indicate the encoding formats of the data being processed. Some encoding formats
0247 require multiple data streams for processing, requiring the specification of both primary data formats (the
0248 encoded data) and secondary data streams (meta-data for the encoded data).
0249
0250 36.2.1.1.1. Primary Input Format
0251
0252 The primary input format code is a 4-bit field when it is used. There are 10 primary input formats available.
0253 The packed formats are not endian neutral. Code values not listed below are reserved.
0254
0255 Code Format Description
0256 0x0 Fixed width byte packed Up to 16 bytes
0257 0x1 Fixed width bit packed Up to 15 bits (CCB version 0) or 23 bits (CCB version
0258 1); bits are read most significant bit to least significant bit
0259 within a byte
0260 0x2 Variable width byte packed Data stream of lengths must be provided as a secondary
0261 input
0262 0x4 Fixed width byte packed with run Up to 16 bytes; data stream of run lengths must be
0263 length encoding provided as a secondary input
0264 0x5 Fixed width bit packed with run Up to 15 bits (CCB version 0) or 23 bits (CCB version
0265 length encoding 1); bits are read most significant bit to least significant bit
0266 within a byte; data stream of run lengths must be provided
0267 as a secondary input
0268 0x8 Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream
0269 Huffman (CCB version 0) or bits are read most significant bit to least significant bit
0270 OZIP (CCB version 1) encoding within a byte; pointer to the encoding table must be
0271 provided
0272 0x9 Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits (CCB version
0273 Huffman (CCB version 0) or 1); compressed stream bits are read most significant bit to
0274 OZIP (CCB version 1) encoding least significant bit within a byte; pointer to the encoding
0275 table must be provided
0276 0xA Variable width byte packed with Up to 16 bytes before the encoding; compressed stream
0277 Huffman (CCB version 0) or bits are read most significant bit to least significant bit
0278 OZIP (CCB version 1) encoding within a byte; data stream of lengths must be provided as
0279 a secondary input; pointer to the encoding table must be
0280 provided
0281
0282
0283 513
0284 Coprocessor services
0285
0286
0287 Code Format Description
0288 0xC Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream
0289 run length encoding, followed by bits are read most significant bit to least significant bit
0290 Huffman (CCB version 0) or within a byte; data stream of run lengths must be provided
0291 OZIP (CCB version 1) encoding as a secondary input; pointer to the encoding table must
0292 be provided
0293 0xD Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits(CCB version 1)
0294 run length encoding, followed by before the encoding; compressed stream bits are read most
0295 Huffman (CCB version 0) or significant bit to least significant bit within a byte; data
0296 OZIP (CCB version 1) encoding stream of run lengths must be provided as a secondary
0297 input; pointer to the encoding table must be provided
0298
0299 If OZIP encoding is used, there must be no reserved bytes in the table.
0300
0301 36.2.1.1.2. Primary Input Element Size
0302
0303 For primary input data streams with fixed size elements, the element size must be indicated in the CCB
0304 command. The size is encoded as the number of bits or bytes, minus one. The valid value range for this
0305 field depends on the input format selected, as listed in the table above.
0306
0307 36.2.1.1.3. Secondary Input Format
0308
0309 For primary input data streams which require a secondary input stream, the secondary input stream is
0310 always encoded in a fixed width, bit-packed format. The bits are read from most significant bit to least
0311 significant bit within a byte. There are two encoding options for the secondary input stream data elements,
0312 depending on whether the value of 0 is needed:
0313
0314 Secondary Input Description
0315 Format Code
0316 0 Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes
0317 to 2, etc)
0318 1 Element is stored as value
0319
0320 36.2.1.1.4. Secondary Input Element Size
0321
0322 Secondary input element size is encoded as a two bit field:
0323
0324 Secondary Input Size Description
0325 Code
0326 0x0 1 bit
0327 0x1 2 bits
0328 0x2 4 bits
0329 0x3 8 bits
0330
0331 36.2.1.1.5. Input Element Offsets
0332
0333 Bit-wise input data streams may have any alignment within the base addressed byte. The offset, specified
0334 from most significant bit to least significant bit, is provided as a fixed 3 bit field for each input type. A
0335 value of 0 indicates that the first input element begins at the most significant bit in the first byte, and a
0336 value of 7 indicates it begins with the least significant bit.
0337
0338 This field should be zero for any byte-wise primary input data streams.
0339
0340
0341 514
0342 Coprocessor services
0343
0344
0345 36.2.1.1.6. Output Format
0346
0347 Query commands support multiple sizes and encodings for output data streams. There are four possible
0348 output encodings, and up to four supported element sizes per encoding. Not all output encodings are
0349 supported for every command. The format is indicated by a 4-bit field in the CCB:
0350
0351 Output Format Code Description
0352 0x0 Byte aligned, 1 byte elements
0353 0x1 Byte aligned, 2 byte elements
0354 0x2 Byte aligned, 4 byte elements
0355 0x3 Byte aligned, 8 byte elements
0356 0x4 16 byte aligned, 16 byte elements
0357 0x5 Reserved
0358 0x6 Reserved
0359 0x7 Reserved
0360 0x8 Packed vector of single bit elements
0361 0x9 Reserved
0362 0xA Reserved
0363 0xB Reserved
0364 0xC Reserved
0365 0xD 2 byte elements where each element is the index value of a bit,
0366 from an bit vector, which was 1.
0367 0xE 4 byte elements where each element is the index value of a bit,
0368 from an bit vector, which was 1.
0369 0xF Reserved
0370
0371 36.2.1.1.7. Application Data Integrity (ADI)
0372
0373 On platforms which support ADI, the ADI version number may be specified for each separate memory
0374 access type used in the CCB command. ADI checking only occurs when reading data. When writing data,
0375 the specified ADI version number overwrites any existing ADI value in memory.
0376
0377 An ADI version value of 0 or 0xF indicates the ADI checking is disabled for that data access, even if it is
0378 enabled in memory. By setting the appropriate flag in CCB_SUBMIT (Section 36.3.1, “ccb_submit”) it is
0379 also an option to disable ADI checking for all inputs accessed via virtual address for all CCBs submitted
0380 during that hypercall invocation.
0381
0382 The ADI value is only guaranteed to be checked on the first 64 bytes of each data access. Mismatches on
0383 subsequent data chunks may not be detected, so guest software should be careful to use page size checking
0384 to protect against buffer overruns.
0385
0386 36.2.1.1.8. Page size checking
0387
0388 All data accesses used in CCB commands must be bounded within a single memory page. When addresses
0389 are provided using a virtual address, the page size for checking is extracted from the TTE for that virtual
0390 address. When using real addresses, the guest must supply the page size in the same field as the address
0391 value. The page size must be one of the sizes supported by the underlying virtual machine. Using a value
0392 that is not supported may result in the CCB submission being rejected or the generation of a CCB parsing
0393 error in the completion area.
0394
0395
0396 515
0397 Coprocessor services
0398
0399
0400 36.2.1.2. Extract command
0401
0402 Converts an input vector in one format to an output vector in another format. All input format types are
0403 supported.
0404
0405 The only supported output format is a padded, byte-aligned output stream, using output codes 0x0 - 0x4.
0406 When the specified output element size is larger than the extracted input element size, zeros are padded to
0407 the extracted input element. First, if the decompressed input size is not a whole number of bytes, 0 bits are
0408 padded to the most significant bit side till the next byte boundary. Next, if the output element size is larger
0409 than the byte padded input element, bytes of value 0 are added based on the Padding Direction bit in the
0410 CCB. If the output element size is smaller than the byte-padded input element size, the input element is
0411 truncated by dropped from the least significant byte side until the selected output size is reached.
0412
0413 The return value of the CCB completion area is invalid. The “number of elements processed” field in the
0414 CCB completion area will be valid.
0415
0416 The extract CCB is a 64-byte “short format” CCB.
0417
0418 The extract CCB command format can be specified by the following packed C structure for a big-endian
0419 machine:
0420
0421
0422 struct extract_ccb {
0423 uint32_t header;
0424 uint32_t control;
0425 uint64_t completion;
0426 uint64_t primary_input;
0427 uint64_t data_access_control;
0428 uint64_t secondary_input;
0429 uint64_t reserved;
0430 uint64_t output;
0431 uint64_t table;
0432 };
0433
0434
0435 The exact field offsets, sizes, and composition are as follows:
0436
0437 Offset Size Field Description
0438 0 4 CCB header (Table 36.1, “CCB Header Format”)
0439 4 4 Command control
0440 Bits Field Description
0441 [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input
0442 Format”)
0443 [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary
0444 Input Element Size”)
0445 [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
0446 Element Offsets”)
0447 [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary
0448 Input Format”)
0449 [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
0450 Element Offsets”)
0451
0452
0453 516
0454 Coprocessor services
0455
0456
0457 Offset Size Field Description
0458 Bits Field Description
0459 [15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
0460 “Secondary Input Element Size”
0461 [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
0462 [9] Padding Direction selector: A value of 1 causes padding bytes
0463 to be added to the left side of output elements. A value of 0
0464 causes padding bytes to be added to the right side of output
0465 elements.
0466 [8:0] Reserved
0467 8 8 Completion
0468 Bits Field Description
0469 [63:60] ADI version (see Section 36.2.1.1.7, “Application Data
0470 Integrity (ADI)”)
0471 [59] If set to 1, a virtual device interrupt will be generated using
0472 the device interrupt number specified in the lower bits of this
0473 completion word. If 0, the lower bits of this completion word
0474 are ignored.
0475 [58:6] Completion area address bits [58:6]. Address type is
0476 determined by CCB header.
0477 [5:0] Virtual device interrupt number for completion interrupt, if
0478 enabled.
0479 16 8 Primary Input
0480 Bits Field Description
0481 [63:60] ADI version (see Section 36.2.1.1.7, “Application Data
0482 Integrity (ADI)”)
0483 [59:56] If using real address, these bits should be filled in with the
0484 page size code for the page boundary checking the guest wants
0485 the virtual machine to use when accessing this data stream
0486 (checking is only guaranteed to be performed when using API
0487 version 1.1 and later). If using a virtual address, this field will
0488 be used as as primary input address bits [59:56].
0489 [55:0] Primary input address bits [55:0]. Address type is determined
0490 by CCB header.
0491 24 8 Data Access Control
0492 Bits Field Description
0493 [63:62] Flow Control
0494 Value Description
0495 0b'00 Disable flow control
0496 0b'01 Enable flow control (only valid with "ORCL,sun4v-
0497 dax-fc" compatible virtual device variants)
0498 0b'10 Reserved
0499 0b'11 Reserved
0500 [61:60] Reserved (API 1.0)
0501
0502
0503 517
0504 Coprocessor services
0505
0506
0507 Offset Size Field Description
0508 Bits Field Description
0509 Pipeline target (API 2.0)
0510 Value Description
0511 0b'00 Connect to primary input
0512 0b'01 Connect to secondary input
0513 0b'10 Reserved
0514 0b'11 Reserved
0515 [59:40] Output buffer size given in units of 64 bytes, minus 1. Value of
0516 0 means 64 bytes, value of 1 means 128 bytes, etc. Buffer size is
0517 only enforced if flow control is enabled in Flow Control field.
0518 [39:32] Reserved
0519 [31:30] Output Data Cache Allocation
0520 Value Description
0521 0b'00 Do not allocate cache lines for output data stream.
0522 0b'01 Force cache lines for output data stream to be
0523 allocated in the cache that is local to the submitting
0524 virtual cpu.
0525 0b'10 Allocate cache lines for output data stream, but allow
0526 existing cache lines associated with the data to remain
0527 in their current cache instance. Any memory not
0528 already in cache will be allocated in the cache local
0529 to the submitting virtual cpu.
0530 0b'11 Reserved
0531 [29:26] Reserved
0532 [25:24] Primary Input Length Format
0533 Value Description
0534 0b'00 Number of primary symbols
0535 0b'01 Number of primary bytes
0536 0b'10 Number of primary bits
0537 0b'11 Reserved
0538 [23:0] Primary Input Length
0539 Format Field Value
0540 # of primary symbols Number of input elements to process,
0541 minus 1. Command execution stops
0542 once count is reached.
0543 # of primary bytes Number of input bytes to process,
0544 minus 1. Command execution stops
0545 once count is reached. The count is
0546 done before any decompression or
0547 decoding.
0548 # of primary bits Number of input bits to process,
0549 minus 1. Command execution stops
0550
0551
0552
0553 518
0554 Coprocessor services
0555
0556
0557 Offset Size Field Description
0558 Bits Field Description
0559 Format Field Value
0560 once count is reached. The count is
0561 done before any decompression or
0562 decoding, and does not include any
0563 bits skipped by the Primary Input
0564 Offset field value of the command
0565 control word.
0566 32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary
0567 Input.
0568 40 8 Reserved
0569 48 8 Output (same fields as Primary Input)
0570 56 8 Symbol Table (if used by Primary Input)
0571 Bits Field Description
0572 [63:60] ADI version (see Section 36.2.1.1.7, “Application Data
0573 Integrity (ADI)”)
0574 [59:56] If using real address, these bits should be filled in with the
0575 page size code for the page boundary checking the guest wants
0576 the virtual machine to use when accessing this data stream
0577 (checking is only guaranteed to be performed when using API
0578 version 1.1 and later). If using a virtual address, this field will
0579 be used as as symbol table address bits [59:56].
0580 [55:4] Symbol table address bits [55:4]. Address type is determined
0581 by CCB header.
0582 [3:0] Symbol table version
0583 Value Description
0584 0 Huffman encoding. Must use 64 byte aligned table
0585 address. (Only available when using version 0 CCBs)
0586 1 OZIP encoding. Must use 16 byte aligned table
0587 address. (Only available when using version 1 CCBs)
0588
0589
0590 36.2.1.3. Scan commands
0591
0592 The scan commands search a stream of input data elements for values which match the selection criteria.
0593 All the input format types are supported. There are multiple formats for the scan commands, allowing the
0594 scan to search for exact matches to one value, exact matches to either of two values, or any value within
0595 a specified range. The specific type of scan is indicated by the command code in the CCB header. For the
0596 scan range commands, the boundary conditions can be specified as greater-than-or-equal-to a value, less-
0597 than-or-equal-to a value, or both by using two boundary values.
0598
0599 There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
0600 0xD, and 0xE). For the standard scan command using the bit vector output, for each input element there
0601 exists one bit in the vector that is set if the input element matched the scan criteria, or clear if not. The
0602 inverted scan command inverts the polarity of the bits in the output. The most significant bit of the first
0603 byte of the output stream corresponds to the first element in the input stream. The standard index array
0604 output format contains one array entry for each input element that matched the scan criteria. Each array
0605
0606
0607
0608 519
0609 Coprocessor services
0610
0611
0612 entry is the index of an input element that matched the scan criteria. An inverted scan command produces
0613 a similar array, but of all the input elements which did NOT match the scan criteria.
0614
0615 The return value of the CCB completion area contains the number of input elements found which match
0616 the scan criteria (or number that did not match for the inverted scans). The “number of elements processed”
0617 field in the CCB completion area will be valid, indicating the number of input elements processed.
0618
0619 These commands are 128-byte “long format” CCBs.
0620
0621 The scan CCB command format can be specified by the following packed C structure for a big-endian
0622 machine:
0623
0624
0625 struct scan_ccb {
0626 uint32_t header;
0627 uint32_t control;
0628 uint64_t completion;
0629 uint64_t primary_input;
0630 uint64_t data_access_control;
0631 uint64_t secondary_input;
0632 uint64_t match_criteria0;
0633 uint64_t output;
0634 uint64_t table;
0635 uint64_t match_criteria1;
0636 uint64_t match_criteria2;
0637 uint64_t match_criteria3;
0638 uint64_t reserved[5];
0639 };
0640
0641
0642 The exact field offsets, sizes, and composition are as follows:
0643
0644 Offset Size Field Description
0645 0 4 CCB header (Table 36.1, “CCB Header Format”)
0646 4 4 Command control
0647 Bits Field Description
0648 [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input
0649 Format”)
0650 [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary
0651 Input Element Size”)
0652 [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
0653 Element Offsets”)
0654 [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary
0655 Input Format”)
0656 [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
0657 Element Offsets”)
0658 [15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
0659 “Secondary Input Element Size”
0660 [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
0661 [9:5] Operand size for first scan criteria value. In a scan value
0662 operation, this is one of two potential extact match values.
0663 In a scan range operation, this is the size of the upper range
0664
0665
0666 520
0667 Coprocessor services
0668
0669
0670 Offset Size Field Description
0671 Bits Field Description
0672 boundary. The value of this field is the number of bytes in the
0673 operand, minus 1. Values 0xF-0x1E are reserved. A value of
0674 0x1F indicates this operand is not in use for this scan operation.
0675 [4:0] Operand size for second scan criteria value. In a scan value
0676 operation, this is one of two potential extact match values.
0677 In a scan range operation, this is the size of the lower range
0678 boundary. The value of this field is the number of bytes in the
0679 operand, minus 1. Values 0xF-0x1E are reserved. A value of
0680 0x1F indicates this operand is not in use for this scan operation.
0681 8 8 Completion (same fields as Section 36.2.1.2, “Extract command”)
0682 16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”)
0683 24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
0684 32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary
0685 Input.
0686 40 4 Most significant 4 bytes of first scan criteria operand. If first operand is less
0687 than 4 bytes, the value is left-aligned to the lowest address bytes.
0688 44 4 Most significant 4 bytes of second scan criteria operand. If second operand
0689 is less than 4 bytes, the value is left-aligned to the lowest address bytes.
0690 48 8 Output (same fields as Primary Input)
0691 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
0692 “Extract command”
0693 64 4 Next 4 most significant bytes of first scan criteria operand occuring after the
0694 bytes specified at offset 40, if needed by the operand size. If first operand
0695 is less than 8 bytes, the valid bytes are left-aligned to the lowest address.
0696 68 4 Next 4 most significant bytes of second scan criteria operand occuring after
0697 the bytes specified at offset 44, if needed by the operand size. If second
0698 operand is less than 8 bytes, the valid bytes are left-aligned to the lowest
0699 address.
0700 72 4 Next 4 most significant bytes of first scan criteria operand occuring after the
0701 bytes specified at offset 64, if needed by the operand size. If first operand
0702 is less than 12 bytes, the valid bytes are left-aligned to the lowest address.
0703 76 4 Next 4 most significant bytes of second scan criteria operand occuring after
0704 the bytes specified at offset 68, if needed by the operand size. If second
0705 operand is less than 12 bytes, the valid bytes are left-aligned to the lowest
0706 address.
0707 80 4 Next 4 most significant bytes of first scan criteria operand occuring after the
0708 bytes specified at offset 72, if needed by the operand size. If first operand
0709 is less than 16 bytes, the valid bytes are left-aligned to the lowest address.
0710 84 4 Next 4 most significant bytes of second scan criteria operand occuring after
0711 the bytes specified at offset 76, if needed by the operand size. If second
0712 operand is less than 16 bytes, the valid bytes are left-aligned to the lowest
0713 address.
0714
0715
0716
0717
0718 521
0719 Coprocessor services
0720
0721
0722 36.2.1.4. Translate commands
0723
0724 The translate commands takes an input array of indicies, and a table of single bit values indexed by those
0725 indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in
0726 the input array. The output should therefore contain exactly one bit per index in the input data stream,
0727 when outputing as a bit vector. When outputing as an index array, the number of elements depends on the
0728 values read in the bit table, but will always be less than, or equal to, the number of input elements. Only
0729 a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP
0730 encoded input streams are allowed. The primary input data element size must be 3 bytes or less.
0731
0732 The maximum table index size allowed is 15 bits, however, larger input elements may be used to provide
0733 additional processing of the output values. If 2 or 3 byte values are used, the least significant 15 bits are
0734 used as an index into the bit table. The most significant 9 bits (when using 3-byte input elements) or single
0735 bit (when using 2-byte input elements) are compared against a fixed 9-bit test value provided in the CCB.
0736 If the values match, the value from the bit table is used as the output element value. If the values do not
0737 match, the output data element value is forced to 0.
0738
0739 In the inverted translate operation, the bit value read from bit table is inverted prior to its use. The additional
0740 additional processing based on any additional non-index bits remains unchanged, and still forces the output
0741 element value to 0 on a mismatch. The specific type of translate command is indicated by the command
0742 code in the CCB header.
0743
0744 There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8,
0745 0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the
0746 output format was a bit array.
0747
0748 The return value of the CCB completion area contains the number of bits set in the output bit vector,
0749 or number of elements in the output index array. The “number of elements processed” field in the CCB
0750 completion area will be valid, indicating the number of input elements processed.
0751
0752 These commands are 64-byte “short format” CCBs.
0753
0754 The translate CCB command format can be specified by the following packed C structure for a big-endian
0755 machine:
0756
0757
0758 struct translate_ccb {
0759 uint32_t header;
0760 uint32_t control;
0761 uint64_t completion;
0762 uint64_t primary_input;
0763 uint64_t data_access_control;
0764 uint64_t secondary_input;
0765 uint64_t reserved;
0766 uint64_t output;
0767 uint64_t table;
0768 };
0769
0770
0771 The exact field offsets, sizes, and composition are as follows:
0772
0773
0774 Offset Size Field Description
0775 0 4 CCB header (Table 36.1, “CCB Header Format”)
0776
0777
0778 522
0779 Coprocessor services
0780
0781
0782 Offset Size Field Description
0783 4 4 Command control
0784 Bits Field Description
0785 [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input
0786 Format”)
0787 [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary
0788 Input Element Size”)
0789 [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
0790 Element Offsets”)
0791 [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary
0792 Input Format”)
0793 [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
0794 Element Offsets”)
0795 [15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
0796 “Secondary Input Element Size”
0797 [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
0798 [9] Reserved
0799 [8:0] Test value used for comparison against the most significant bits
0800 in the input values, when using 2 or 3 byte input elements.
0801 8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
0802 16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”
0803 24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”,
0804 except Primary Input Length Format may not use the 0x0 value)
0805 32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary
0806 Input.
0807 40 8 Reserved
0808 48 8 Output (same fields as Primary Input)
0809 56 8 Bit Table
0810 Bits Field Description
0811 [63:60] ADI version (see Section 36.2.1.1.7, “Application Data
0812 Integrity (ADI)”)
0813 [59:56] If using real address, these bits should be filled in with the
0814 page size code for the page boundary checking the guest wants
0815 the virtual machine to use when accessing this data stream
0816 (checking is only guaranteed to be performed when using API
0817 version 1.1 and later). If using a virtual address, this field will
0818 be used as as bit table address bits [59:56]
0819 [55:4] Bit table address bits [55:4]. Address type is determined by
0820 CCB header. Address must be 64-byte aligned (CCB version
0821 0) or 16-byte aligned (CCB version 1).
0822 [3:0] Bit table version
0823 Value Description
0824 0 4KB table size
0825 1 8KB table size
0826
0827
0828
0829 523
0830 Coprocessor services
0831
0832
0833 36.2.1.5. Select command
0834 The select command filters the primary input data stream by using a secondary input bit vector to determine
0835 which input elements to include in the output. For each bit set at a given index N within the bit vector,
0836 the Nth input element is included in the output. If the bit is not set, the element is not included. Only a
0837 restricted subset of the possible input format types are supported. No variable width or run length encoded
0838 input streams are allowed, since the secondary input stream is used for the filtering bit vector.
0839
0840 The only supported output format is a padded, byte-aligned output stream. The stream follows the same
0841 rules and restrictions as padded output stream described in Section 36.2.1.2, “Extract command”.
0842
0843 The return value of the CCB completion area contains the number of bits set in the input bit vector. The
0844 "number of elements processed" field in the CCB completion area will be valid, indicating the number
0845 of input elements processed.
0846
0847 The select CCB is a 64-byte “short format” CCB.
0848
0849 The select CCB command format can be specified by the following packed C structure for a big-endian
0850 machine:
0851
0852
0853 struct select_ccb {
0854 uint32_t header;
0855 uint32_t control;
0856 uint64_t completion;
0857 uint64_t primary_input;
0858 uint64_t data_access_control;
0859 uint64_t secondary_input;
0860 uint64_t reserved;
0861 uint64_t output;
0862 uint64_t table;
0863 };
0864
0865
0866 The exact field offsets, sizes, and composition are as follows:
0867
0868 Offset Size Field Description
0869 0 4 CCB header (Table 36.1, “CCB Header Format”)
0870 4 4 Command control
0871 Bits Field Description
0872 [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input
0873 Format”)
0874 [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary
0875 Input Element Size”)
0876 [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input
0877 Element Offsets”)
0878 [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary
0879 Input Format”)
0880 [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
0881 Element Offsets”)
0882 [15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
0883 “Secondary Input Element Size”
0884
0885
0886 524
0887 Coprocessor services
0888
0889
0890 Offset Size Field Description
0891 Bits Field Description
0892 [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
0893 [9] Padding Direction selector: A value of 1 causes padding bytes
0894 to be added to the left side of output elements. A value of 0
0895 causes padding bytes to be added to the right side of output
0896 elements.
0897 [8:0] Reserved
0898 8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
0899 16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”
0900 24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
0901 32 8 Secondary Bit Vector Input. Same fields as Primary Input.
0902 40 8 Reserved
0903 48 8 Output (same fields as Primary Input)
0904 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2,
0905 “Extract command”
0906
0907 36.2.1.6. No-op and Sync commands
0908 The no-op (no operation) command is a CCB which has no processing effect. The CCB, when processed
0909 by the virtual machine, simply updates the completion area with its execution status. The CCB may have
0910 the serial-conditional flags set in order to restrict when it executes.
0911
0912 The sync command is a variant of the no-op command which with restricted execution timing. A sync
0913 command CCB will only execute when all previous commands submitted in the same request have
0914 completed. This is stronger than the conditional flag sequencing, which is only dependent on a single
0915 previous serial CCB. While the relative ordering is guaranteed, virtual machine implementations with
0916 shared hardware resources may cause the sync command to wait for longer than the minimum required
0917 time.
0918
0919 The return value of the CCB completion area is invalid for these CCBs. The “number of elements
0920 processed” field is also invalid for these CCBs.
0921
0922 These commands are 64-byte “short format” CCBs.
0923
0924 The no-op CCB command format can be specified by the following packed C structure for a big-endian
0925 machine:
0926
0927
0928 struct nop_ccb {
0929 uint32_t header;
0930 uint32_t control;
0931 uint64_t completion;
0932 uint64_t reserved[6];
0933 };
0934
0935
0936 The exact field offsets, sizes, and composition are as follows:
0937
0938 Offset Size Field Description
0939 0 4 CCB header (Table 36.1, “CCB Header Format”)
0940
0941
0942 525
0943 Coprocessor services
0944
0945
0946 Offset Size Field Description
0947 4 4 Command control
0948 Bits Field Description
0949 [31] If set, this CCB functions as a Sync command. If clear, this
0950 CCB functions as a No-op command.
0951 [30:0] Reserved
0952 8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
0953 16 46 Reserved
0954
0955 36.2.2. CCB Completion Area
0956 All CCB commands use a common 128-byte Completion Area format, which can be specified by the
0957 following packed C structure for a big-endian machine:
0958
0959
0960 struct completion_area {
0961 uint8_t status_flag;
0962 uint8_t error_note;
0963 uint8_t rsvd0[2];
0964 uint32_t error_values;
0965 uint32_t output_size;
0966 uint32_t rsvd1;
0967 uint64_t run_time;
0968 uint64_t run_stats;
0969 uint32_t elements;
0970 uint8_t rsvd2[20];
0971 uint64_t return_value;
0972 uint64_t extra_return_value[8];
0973 };
0974
0975
0976 The Completion Area must be a 128-byte aligned memory location. The exact layout can be described
0977 using byte offsets and sizes relative to the memory base:
0978
0979 Offset Size Field Description
0980 0 1 CCB execution status
0981 0x0 Command not yet completed
0982 0x1 Command ran and succeeded
0983 0x2 Command ran and failed (partial results may be been
0984 produced)
0985 0x3 Command ran and was killed (partial execution may
0986 have occurred)
0987 0x4 Command was not run
0988 0x5-0xF Reserved
0989 1 1 Error reason code
0990 0x0 Reserved
0991 0x1 Buffer overflow
0992
0993
0994 526
0995 Coprocessor services
0996
0997
0998 Offset Size Field Description
0999 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 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 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 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 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 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 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 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
