2 * Copyright 2010-2013 Intel Corporation.
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License as published
6 * by the Free Software Foundation, version 2.1.
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * Lesser General Public License for more details.
13 * You should have received a copy of the GNU Lesser General Public
14 * License along with this library; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18 * Disclaimer: The codes contained in these modules may be specific
19 * to the Intel Software Development Platform codenamed Knights Ferry,
20 * and the Intel product codenamed Knights Corner, and are not backward
21 * compatible with other Intel products. Additionally, Intel will NOT
22 * support the codes or instruction set in future products.
24 * Intel offers no warranty of any kind regarding the code. This code is
25 * licensed on an "AS IS" basis and Intel is not obligated to provide
26 * any support, assistance, installation, training, or other services
27 * of any kind. Intel is also not obligated to provide any updates,
28 * enhancements or extensions. Intel specifically disclaims any warranty
29 * of merchantability, non-infringement, fitness for any particular
30 * purpose, and any other warranty.
32 * Further, Intel disclaims all liability of any kind, including but
33 * not limited to liability for infringement of any proprietary rights,
34 * relating to the use of the code, even if Intel is notified of the
35 * possibility of such liability. Except as expressly stated in an Intel
36 * license agreement provided with this code and agreed upon with Intel,
37 * no license, express or implied, by estoppel or otherwise, to any
38 * intellectual property rights is granted herein.
41 #ifndef _COIBUFFER_SOURCE_H
42 #define _COIBUFFER_SOURCE_H
44 /** @ingroup COIBuffer
45 * @addtogroup COIBufferSource
48 * @file source\COIBuffer_source.h
50 #ifndef DOXYGEN_SHOULD_SKIP_THIS
51 #include "../common/COITypes_common.h"
52 #include "../common/COIResult_common.h"
53 #endif // DOXYGEN_SHOULD_SKIP_THIS
60 ///////////////////////////////////////////////////////////////////////////////
61 /// The valid buffer types that may be created using COIBufferCreate.
62 /// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix
63 /// below which describes the valid combinations of buffer types and flags.
65 typedef enum COI_BUFFER_TYPE
67 /// Normal buffers exist as a single physical buffer in either Source or
68 /// Sink physical memory. Mapping the buffer may stall the pipelines.
69 COI_BUFFER_NORMAL
= 1,
71 /// A streaming buffer creates new versions each time it is passed to
72 /// Runfunction. These new versions are consumed by run functions.
74 /// To_SINK buffers are used to send data from SOURCE to SINK
75 /// These buffers are SOURCE write only buffers. If read, won't
76 /// get Data written by SINK
77 COI_BUFFER_STREAMING_TO_SINK
,
79 /// To_SOURCE buffers are used to get data from SINK to SOURCE
80 /// These buffers are SOURCE Read only buffers. If written, data
81 /// won't get reflected on SINK side.
82 COI_BUFFER_STREAMING_TO_SOURCE
,
84 /// A pinned buffer exists in a shared memory region and is always
85 /// available for read or write operations.
88 /// OpenCL buffers are similar to Normal buffers except they don't
89 /// stall pipelines and don't follow any read write dependencies.
95 /// @name COIBUFFER creation flags.
96 /// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix
97 /// below which describes the valid combinations of buffer types and flags.
100 /// Create the buffer such that it has the same virtual address on all of the
101 /// sink processes with which it is associated.
102 #define COI_SAME_ADDRESS_SINKS 0x00000001
104 /// Create the buffer such that it has the same virtual address on all of the
105 /// sink processes with which it is associated and in the source process.
106 #define COI_SAME_ADDRESS_SINKS_AND_SOURCE 0x00000002
108 /// Hint to the runtime that the source will frequently read the buffer
109 #define COI_OPTIMIZE_SOURCE_READ 0x00000004
111 /// Hint to the runtime that the source will frequently write the buffer
112 #define COI_OPTIMIZE_SOURCE_WRITE 0x00000008
114 /// Hint to the runtime that the sink will frequently read the buffer
115 #define COI_OPTIMIZE_SINK_READ 0x00000010
117 /// Hint to the runtime that the sink will frequently write the buffer
118 #define COI_OPTIMIZE_SINK_WRITE 0x00000020
120 /// Used to delay the pinning of memory into physical pages, until required
121 /// for DMA. This can be used to delay the cost of time spent pinning memory
122 /// until absolutely necessary. Might speed up the execution of COIBufferCreate
123 /// calls, but slow down the first access of the buffer in
124 /// COIPipelineRunFunction(s) or other COIBuffer access API's.
125 /// Also of important note, that with this flag enabled COI will not be able to
126 /// check to see if this memory is read only. Ordinarily this is checked
127 /// and an error is thrown upon buffer creation. With this flag, the error
128 /// might occur later, and cause undetermined behavior. Be sure to always
129 /// use writeable memory for COIBuffers.
130 #define COI_OPTIMIZE_NO_DMA 0x00000040
132 /// Hint to the runtime to try to use huge page sizes for backing store on the
133 /// sink. Is currently not compatible with PINNED buffers or the SAME_ADDRESS
134 /// flags or the SINK_MEMORY flag.
135 #define COI_OPTIMIZE_HUGE_PAGE_SIZE 0x00000080
137 /// Used to tell Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
138 /// to create a buffer using memory that has already been
139 /// allocated on the sink. This flag is only valid when passed in to the
140 /// COIBufferCreateFromMemory API.
141 #define COI_SINK_MEMORY 0x00000100
145 #ifndef DOXYGEN_SHOULD_SKIP_THIS
146 // Make the flag mask
155 #define MTM(_BUFFER, B1, B2, B3, B4, B5, B6, B7, B8, B9) \
156 (B1 | B2<<1 | B3<<2 | B4<<3 | B5<<4 | B6<<5 | B7<<6 | B8<<7 | B9<<8)
159 /// \enum COI_BUFFER_TYPE
160 /// This matrix shows the valid combinations of buffer types and buffer flags
161 /// that may be passed in to COIBufferCreate and COIBufferCreateFromMemory.
163 static const uint64_t
164 COI_VALID_BUFFER_TYPES_AND_FLAGS
[COI_BUFFER_OPENCL
+1] = {
165 /* | | SAME | | | | | | | |
166 | SAME | ADDR | OPT | OPT | OPT | OPT | OPT | HUGE | COI |
167 | ADDR | SINK | SRC | SRC | SINK | SINK | NO | PAGE | SINK |
168 | SINKS | SRC | READ | WRITE | READ | WRITE | DMA | SIZE | MEM |
169 +-------+------+------+-------+------+-------+-----+------+-----*/
170 MTM(INVALID
, F
, F
, F
, F
, F
, F
, F
, F
, F
),
171 MTM(NORMAL
, T
, T
, T
, T
, T
, T
, T
, T
, T
),
172 MTM(TO_SINK
, F
, F
, F
, T
, T
, T
, F
, F
, F
),
173 MTM(TO_SOURCE
, F
, F
, T
, F
, F
, T
, F
, F
, F
),
174 MTM(PINNED
, T
, T
, T
, T
, T
, T
, F
, F
, F
),
175 MTM(OPENCL
, T
, T
, T
, T
, T
, T
, T
, T
, F
),
180 //////////////////////////////////////////////////////////////////////////////
181 /// These flags control how the buffer will be accessed on the source after
183 /// Please see the COI_VALID_BUFFER_TYPES_AND_MAP matrix below for the
184 /// valid buffer type and map operation combinations.
185 typedef enum COI_MAP_TYPE
187 /// Allows the application to read and write the contents of the buffer
188 /// after it is mapped.
189 COI_MAP_READ_WRITE
= 1,
191 /// If this flag is set then the application must only read from the
192 /// buffer after it is mapped. If the application writes to the buffer
193 /// the contents will not be reflected back to the sink or stored for
194 /// the next time the buffer is mapped on the source.
195 /// This allows the runtime to make significant performance optimizations
196 /// in buffer handling.
199 /// Setting this flag means that the source will overwrite the entire
200 /// buffer once it is mapped. The app must not read from the buffer and
201 /// must not expect the contents of the buffer to be synchronized from
202 /// the sink side during the map operation.
203 /// This allows the runtime to make significant performance optimizations
204 /// in buffer handling.
205 COI_MAP_WRITE_ENTIRE_BUFFER
208 #ifndef DOXYGEN_SHOULD_SKIP_THIS
209 // Make the flag mask
210 #define MMM(_BUFFER, B1, B2, B3) \
213 /// \enum COI_MAP_TYPE
214 /// This matrix shows the valid combinations of buffer types and map
215 /// operations that may be passed in to COIBufferMap.
217 static const uint64_t
218 COI_VALID_BUFFER_TYPES_AND_MAP
219 [COI_BUFFER_OPENCL
+1][COI_MAP_WRITE_ENTIRE_BUFFER
+1] = {
220 /* | MAP | MAP | MAP |
221 | READ | READ | WRITE |
222 | WRITE | ONLY | ENTIRE|
223 +-------+-------+-------+*/
224 MMM(INVALID
, F
, F
, F
),
225 MMM(NORMAL
, T
, T
, T
),
226 MMM(STREAMING_TO_SINK
, F
, F
, T
),
227 MMM(STREAMING_TO_SOURCE
, F
, T
, F
),
228 MMM(PINNED
, T
, T
, T
),
229 MMM(OPENCL
, T
, T
, T
),
233 #ifndef DOXYGEN_SHOULD_SKIP_THIS
238 //////////////////////////////////////////////////////////////////////////////
239 /// The valid copy operation types for the COIBufferWrite, COIBufferRead,
240 /// and COIBufferCopy APIs.
242 typedef enum COI_COPY_TYPE
244 /// The runtime can pick the best suitable way to copy the data.
245 COI_COPY_UNSPECIFIED
= 0,
247 /// The runtime should use DMA to copy the data.
250 /// The runtime should use a CPU copy to copy the data.
251 /// CPU copy is a synchronous copy. So the resulting operations are always
252 /// blocking (even though a out_pCompletion event is specified).
258 //////////////////////////////////////////////////////////////////////////////
259 /// The buffer states are used to indicate whether a buffer is available for
260 /// access in a COIPROCESS. This is used with COIBufferSetState.
262 /// Buffer state holds only for NORMAL Buffers and OPENCL buffers. Pinned
263 /// buffers are always valid everywhere they get created. Streaming buffers
264 /// do not follow the state transition rules, as a new version of the
265 /// buffer is created every time it is Mapped or you issue a RunFunction.
267 /// Rules on State Transition of the buffer:
268 /// -. When a Buffer is created by default it is valid only on the source,
269 /// except for buffers created with COI_SINK_MEMORY flag which are valid
270 /// only on the sink where the memory lies when created.
271 /// -. Apart from SetState following APIs also alters the state of the buffer
274 /// - COIBufferMap alters state of buffer depending on the COI_MAP_TYPE.
275 /// COI_MAP_READ_ONLY: Makes Valid on the Source. Doesn't affect the state
276 /// of the buffer on the other devices.
277 /// COI_MAP_READ_WRITE: Makes it Valid only the Source and Invalid
278 /// everywhere else. OPENCL buffers are invalidated
279 /// only if it is not in use.
280 /// COI_MAP_WRITE_ENTIRE_BUFFER: Makes it valid only on the Source. OPENCL
281 /// buffers are invalidated only if not in use.
283 /// - COIPipelineRunfunction alters the state of the buffer depending on the
285 /// COI_SINK_READ: Makes it valid on the sink where RunFunction is being
286 /// issued. Doesn't affect the state of the buffer on other
288 /// COI_SINK_WRITE: Makes it valid only on the sink where Runfunction is
289 /// being issued and invalid everywhere else. OPENCL
290 /// buffers are invalidated only if the buffer is not in
292 /// COI_SINK_WRITE_ENTIRE: Makes it valid only on the sink where
293 /// Runfunction is being issued and invalid everywhere else
294 /// OPENCL buffers are invalidated only if the buffer is
297 /// - COIBufferWrite makes the buffer exclusively valid where the write
298 /// happens. Write gives preference to Source over Sink. In other words
299 /// if a buffer is valid on the Source and multiple Sinks, Write will
300 /// happen on the Source and will Invalidate all other Sinks. If the
301 /// buffer is valid on multiple Sinks ( and not on the Source) then
302 /// Intel® Coprocessor Offload Infrastructure (Intel® COI)
303 /// selects process handle with the lowest numerical value to do the
304 /// exclusive write Again, OPENCL buffers are invalidated only if the
305 /// buffer is not in use on that SINK/SOURCE.
307 /// The preference rule mentioned above holds true even for SetState API,
308 /// when data needs to be moved from a valid location. The selection of
309 /// valid location happens as stated above.
311 /// - It is possible to alter only parts of the buffer and change it state
312 /// In other words it is possible for different parts of the buffer to have
313 /// different states on different devices. A byte is the minimum size at
314 /// which state can be maintained internally. Granularity level is completely
315 /// determined by how the buffer gets fragmented.
317 /// Note: Buffer is considered 'in use' if is
318 /// - Being used in RunFunction : In use on a Sink
319 /// - Mapped: In use on a Source
320 /// - AddRef'd: In use on Sink
323 //////////////////////////////////////////////////////////////////////////////
324 /// The buffer states used with COIBufferSetState call to indicate the new
325 /// state of the buffer on a given process
328 COI_BUFFER_VALID
= 0, // Buffer is valid and up-to-date on the process
329 COI_BUFFER_INVALID
, // Buffer is not valid, need valid data
330 COI_BUFFER_VALID_MAY_DROP
, // Same as valid but will drop the content when
331 // evicted to avoid overwriting the shadow
333 COI_BUFFER_RESERVED
// Reserved for internal use
336 /// Note: A VALID_MAY_DROP declares a buffer's copy as secondary on a given
337 /// process. This means that there needs to be at least one primary copy of the
338 /// the buffer somewhere in order to mark the buffer as VALID_MAY_DROP on a
339 /// process. In other words to make a buffer VALID_MAY_DROP on a given process
340 /// it needs to be in COI_BUFFER_VALID state somewhere else. The operation gets
341 /// ignored (or is a nop) if there is no primary copy of the buffer. The nature
342 /// of this state to "drop the content" when evicted is a side effect of
343 /// marking the buffer as secondary copy. So when a buffer marked
344 /// VALID_MAY_DROP is evicted Intel® Coprocessor Offload Infrastructure
345 /// (Intel® COI) doesn't back it up as it is assumed that
346 /// there is a primary copy somewhere.
348 //////////////////////////////////////////////////////////////////////////////
349 /// The buffer move flags are used to indicate when a buffer should be moved
350 /// when it's state is changed. This is used with COIBufferSetState.
352 COI_BUFFER_MOVE
= 0,// Dirty data is moved if state change requires it
353 COI_BUFFER_NO_MOVE
// Change state without moving data
354 } COI_BUFFER_MOVE_FLAG
;
356 // A process handle for COIBufferSetState call to indicate all the sink
357 // processes where the given buffer is valid
358 #define COI_SINK_OWNERS ((COIPROCESS)-2)
360 //////////////////////////////////////////////////////////////////////////////
362 /// Creates a buffer that can be used in RunFunctions that are queued in
363 /// pipelines. The address space for the buffer is reserved when it is
364 /// created although the memory may not be committed until the buffer is
365 /// used for the first time. Please note that the Intel® Coprocessor Offload
366 /// Infrastructure (Intel® COI) runtime may also
367 /// allocate space for the source process to use as shadow memory for
368 /// certain types of buffers. If Intel® Coprocessor Offload Infrastructure
369 /// (Intel® COI) does allocate this memory it will not
370 /// be released or reallocated until the COIBuffer is destroyed.
373 /// [in] The number of bytes to allocate for the buffer. If in_Size
374 /// is not page aligned, it will be rounded up.
377 /// [in] The type of the buffer to create.
380 /// [in] A bitmask of attributes for the newly created buffer.
381 /// Some of these flags are required for correctness while others
382 /// are provided as hints to the runtime system so it can make
383 /// certain performance optimizations.
385 /// @param in_pInitData
386 /// [in] If non-NULL the buffer will be initialized with the data
387 /// pointed to by pInitData. The memory at in_pInitData must hold
388 /// at least in_Size bytes.
390 /// @param in_NumProcesses
391 /// [in] The number of processes with which this buffer might be used.
393 /// @param in_pProcesses
394 /// [in] An array of COIPROCESS handles identifying the processes with
395 /// which this buffer might be used.
397 /// @param out_pBuffer
398 /// [out] Pointer to a buffer handle. The handle will be filled in
399 /// with a value that uniquely identifies the newly created buffer.
400 /// This handle should be disposed of via COIBufferDestroy()
401 /// once it is no longer needed.
403 /// @return COI_SUCCESS if the buffer was created
405 /// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters
406 /// are not compatible with one another. Please see the
407 /// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about
408 /// which flags and types are compatible.
410 /// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in
411 /// the in_Flags parameter are not recognized flags, or if
412 /// in_NumProcesses is zero.
414 /// @return COI_INVALID_POINTER if the in_pProcesses or out_pBuffer parameter
417 /// @return COI_NOT_SUPPORTED if one of the in_Flags is COI_SINK_MEMORY.
419 /// @return COI_NOT_SUPPORTED if the flags include either
420 /// COI_SAME_ADDRESS_SINKS or COI_SAME_ADDRESS_SINKS_AND_SOURCE and
421 /// COI_OPTIMIZE_HUGE_PAGE_SIZE.
423 /// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the
424 /// in_pProcesses array does not identify a valid process.
426 /// @return COI_OUT_OF_MEMORY if allocating the buffer fails.
428 /// @return COI_RESOURCE_EXHAUSTED if the sink is out of buffer memory.
434 COI_BUFFER_TYPE in_Type
,
436 const void* in_pInitData
,
437 uint32_t in_NumProcesses
,
438 const COIPROCESS
* in_pProcesses
,
439 COIBUFFER
* out_pBuffer
);
441 //////////////////////////////////////////////////////////////////////////////
443 /// Creates a buffer from some existing memory that can be used in
444 /// RunFunctions that are queued in pipelines. If the flag COI_SINK_MEMORY
445 /// is specified then Intel® Coprocessor Offload I
446 /// nfrastructure (Intel® COI) will use that memory for the buffer on the sink.
447 /// If that flag isn't set then the memory provided is used as backing store
448 /// for the buffer on the source. In either case the memory must not be freed
449 /// before the buffer is destroyed.
450 /// While the user still owns the memory passed in they must use the
451 /// appropriate access flags when accessing the buffer in COIPipelinRunFunction
452 /// or COIBufferMap calls so that the runtime knows when the
453 /// memory has been modified. If the user just writes directly to the memory
454 /// location then those changes may not be visible when the corresponding
455 /// buffer is accessed.
456 /// Whatever values are already present in the memory location when this call
457 /// is made are preserved. The memory values are also preserved when
458 /// COIBufferDestroy is called.
460 /// @warning: Use of this function is highly discouraged if the calling program
461 /// program forks at all (including calls to system(3), popen(3), or similar
462 /// functions) during the life of this buffer. See the discussion around the
463 /// in_Memory parameter below regarding this.
466 /// [in] The size of in_Memory in bytes. If in_Size
467 /// is not page aligned, it will be rounded up.
470 /// [in] The type of the buffer to create. Note that streaming buffers
471 /// can not be created from user memory. Only COI_BUFFER_NORMAL and
472 /// COI_BUFFER_PINNED buffer types are supported.
475 /// [in] A bitmask of attributes for the newly created buffer.
476 /// Some of these flags are required for correctness while others
477 /// are provided as hints to the runtime system so it can make
478 /// certain performance optimizations. Note that the flag
479 /// COI_SAME_ADDRESS_SINKS_AND_SOURCE is still valid but may fail
480 /// if the same address as in_Memory can not be allocated on the sink.
483 /// [in] A pointer to an already allocated memory region
484 /// that should be turned into a COIBUFFER. Although the user still
485 /// owns this memory they should not free it before calling
486 /// COIBufferDestroy. They must also only access the memory using
487 /// COIBUFFER semantics, for example using COIBufferMap/COIBufferUnmap
488 /// when they wish to read or write the data. There are no alignment
489 /// or size requirements for this memory region.
492 /// Since the backing memory passed in can be the target of a DMA
493 /// the caller must ensure that there is no call to clone(2) (without
494 /// the CLONE_VM argument) during the life of this buffer. This
495 /// includes higher level functions that call clone such as fork(2),
496 /// system(3), popen(3), among others).
498 /// For forked processes, Linux uses copy-on-write semantics for
499 /// performances reasons. Conseqeuently, if the parent forks and then
500 /// writes to this memory, the physical page mapping changes causing
501 /// the DMA to fail (and thus data corruption).
503 /// In Linux you can mark a set of pages to not be copied across
504 /// across the clone by calling madvise(2) with an argument of
505 /// MADV_DONTFORK and then safely use that memory in this scenario.
506 /// Alternately, if the memory is from a region marked MAP_SHARED,
509 /// @param in_NumProcesses
510 /// [in] The number of processes with which this buffer might be used.
511 /// If the flag COI_SINK_MEMORY is specified then this must be 1.
513 /// @param in_pProcesses
514 /// [in] An array of COIPROCESS handles identifying the processes with
515 /// which this buffer might be used.
517 /// @param out_pBuffer
518 /// [out] Pointer to a buffer handle. The handle will be filled in
519 /// with a value that uniquely identifies the newly created buffer.
520 /// This handle should be disposed of via COIBufferDestroy()
521 /// once it is no longer needed.
523 /// @return COI_SUCCESS if the buffer was created
525 /// @return COI_NOT_SUPPORTED if the in_Type value is not COI_BUFFER_NORMAL or
526 /// COI_BUFFER_PINNED.
528 /// @return COI_NOT_SUPPORTED if in_Memory is read-only memory
530 /// @return COI_NOT_SUPPORTED if one of the in_Flags is COI_SINK_MEMORY and
531 /// in_Type is not COI_BUFFER_NORMAL
533 /// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS is set
535 /// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS_AND_SOURCE is
538 /// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters
539 /// are not compatible with one another. Please see the
540 /// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about
541 /// which flags and types are compatible.
543 /// @return COI_ARGUMENT_MISMATCH if the flag COI_SINK_MEMORY is specified and
544 /// in_NumProcesses > 1.
546 /// @return COI_ARGUMENT_MISMATCH if the flags COI_SINK_MEMORY and
547 /// COI_OPTIMIZE_HUGE_PAGE_SIZE are both set.
549 /// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in
550 /// the in_Flags parameter are not recognized flags, or if
551 /// in_NumProcesses is zero.
553 /// @return COI_INVALID_POINTER if in_Memory, in_pProcesses or
554 /// out_pBuffer parameter is NULL.
556 /// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the
557 /// in_pProcesses array does not identify a valid process.
561 COIBufferCreateFromMemory(
563 COI_BUFFER_TYPE in_Type
,
566 uint32_t in_NumProcesses
,
567 const COIPROCESS
* in_pProcesses
,
568 COIBUFFER
* out_pBuffer
);
571 //////////////////////////////////////////////////////////////////////////////
573 /// Destroys a buffer. Will block on completion of any operations on the
574 /// buffer, such as COIPipelineRunFunction or COIBufferCopy. Will block until
575 /// all COIBufferAddRef calls have had a matching COIBufferReleaseRef call
576 /// made. Will not block on an outstanding COIBufferUnmap but will instead
577 /// return COI_RETRY.
580 /// [in] Handle of the buffer to destroy.
582 /// @return COI_SUCCESS if the buffer was destroyed.
584 /// @return COI_INVALID_HANDLE if the buffer handle was invalid.
586 /// @return COI_RETRY if the buffer is currently mapped. The buffer must
587 /// first be unmapped before it can be destroyed.
589 /// @return COI_RETRY if the sub-buffers created from this buffer are not yet
595 COIBUFFER in_Buffer
);
598 //////////////////////////////////////////////////////////////////////////////
600 /// This call initiates a request to access a region of a buffer. Multiple
601 /// overlapping (or non overlapping) regions can be mapped simultaneously for
602 /// any given buffer. If a completion event is specified this call will
603 /// queue a request for the data which will be satisfied when the buffer is
604 /// available. Once all conditions are met the completion event will be
605 /// signaled and the user can access the data at out_ppData. The user can call
606 /// COIEventWait with out_pCompletion to find out when the map operation has
607 /// completed. If the user accesses the data before the map operation is
608 /// complete the results are undefined. If out_pCompletion is NULL then this
609 /// call blocks until the map operation completes and when this call returns
610 /// out_ppData can be safely accessed. This call returns a map instance handle
611 /// in an out parameter which must be passed into COIBufferUnmap when the user
612 /// no longer needs access to that region of the buffer.
614 /// The address returned from COIBufferMap may point to memory that
615 /// Intel® Coprocessor Offload Infrastructure (Intel® COI)
616 /// manages on behalf of the user. The user must not free or reallocate this
617 /// memory, Intel® Coprocessor Offload Infrastructure (Intel® COI)
618 /// will perform any necessary cleanup when the buffer is
621 /// Note that different types of buffers behave differently when mapped.
622 /// For instance, mapping a COI_BUFFER_NORMAL for write must stall if the
623 /// buffer is currently being written to by a run function. Mapping a
624 /// COI_BUFFER_STREAMING_TO_SINK will create a new physical copy of the buffer
625 /// and make it available immediately. Mapping a COI_BUFFER_PINNED buffer will
626 /// not affect other functions that use that buffer since a COI_BUFFER_PINNED
627 /// buffer can be mapped at any time.
628 /// The asynchronous operation of COIBufferMap will likely be most useful when
629 /// paired with a COI_BUFFER_NORMAL.
632 /// [in] Handle for the buffer to map.
635 /// [in] Offset into the buffer that a pointer should be returned
636 /// for. The value 0 can be passed in to signify that the mapped
637 /// region should start at the beginning of the buffer.
640 /// [in] Length of the buffer area to map. This parameter, in
641 /// combination with in_Offset, allows the caller to specify
642 /// that only a subset of an entire buffer need be mapped. A
643 /// value of 0 can be passed in only if in_Offset is 0, to signify
644 /// that the mapped region is the entire buffer.
647 /// [in] The access type that is needed by the application. This will
648 /// affect how the data can be accessed once the map operation
649 /// completes. See the COI_MAP_TYPE enum for more details.
651 /// @param in_NumDependencies
652 /// [in] The number of dependencies specified in the in_pDependencies
653 /// array. This may be 0 if the caller does not want the map
654 /// call initiation to wait for any events to be signaled before
655 /// starting the map operations.
657 /// @param in_pDependencies
658 /// [in] An optional array of handles to previously created COIEVENT
659 /// objects that this map operation will wait for before starting.
660 /// This allows the user to create dependencies between asynchronous
661 /// map calls and other operations such as run functions or other
662 /// asynchronous map calls. The user may pass in NULL if they do not
663 /// wish to wait for any dependencies to complete before initiating map
666 /// @param out_pCompletion
667 /// [out] An optional pointer to a COIEVENT object
668 /// that will be signaled when a map call with the passed in buffer
669 /// would complete immediately, that is, the buffer memory has been
670 /// allocated on the source and its contents updated. The user may pass
671 /// in NULL if the user wants COIBufferMap to perform a blocking map
674 /// @param out_pMapInstance
675 /// [out] A pointer to a COIMAPINSTANCE which represents this mapping
676 /// of the buffer and must be passed in to COIBufferUnmap when access
677 /// to this region of the buffer data is no longer needed.
679 /// @param out_ppData
680 /// [out] Pointer to the buffer data. The data will only be valid
681 /// when the completion object is signaled, or for a synchronous
682 /// map operation with the call to map returns.
685 /// @return COI_SUCCESS if the map request succeeds.
687 /// @return COI_OUT_OF_RANGE if in_Offset of (in_Offset + in_Length) exceeds
688 /// the size of the buffer.
690 /// @return COI_OUT_OF_RANGE if in_Length is 0, but in_Offset is not 0.
692 /// @return COI_OUT_OF_RANGE if in_Type is not a valid COI_MAP_TYPE.
694 /// @return COI_ARGUMENT_MISMATCH if in_NumDependencies is non-zero while
695 /// in_pDependencies was passed in as NULL.
697 /// @return COI_ARGUMENT_MISMATCH if in_pDependencies is non-NULL but
698 /// in_NumDependencies is zero.
700 /// @return COI_ARGUMENT_MISMATCH if the in_Type of map is not a valid type
701 /// for in_Buffer's type of buffer.
703 /// @return COI_RESOURCE_EXHAUSTED if could not create a version for TO_SINK
704 /// streaming buffer. It can fail if enough memory is not available to
705 /// register. This call will succeed eventually when the registered
706 /// memory becomes available.
708 /// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle.
710 /// @return COI_INVALID_POINTER if out_pMapInstance or out_ppData is NULL.
718 COI_MAP_TYPE in_Type
,
719 uint32_t in_NumDependencies
,
720 const COIEVENT
* in_pDependencies
,
721 COIEVENT
* out_pCompletion
,
722 COIMAPINSTANCE
* out_pMapInstance
,
725 //////////////////////////////////////////////////////////////////////////////
727 /// Disables Source access to the region of the buffer that was provided
728 /// through the corresponding call to COIBufferMap. The number of calls to
729 /// COIBufferUnmap() should always match the number of calls made to
730 /// COIBufferMap(). The data pointer returned from the COIBufferMap() call
731 /// will be invalid after this call.
733 /// @param in_MapInstance
734 /// [in] buffer map instance handle to unmap.
736 /// @param in_NumDependencies
737 /// [in] The number of dependencies specified in the in_pDependencies
738 /// array. This may be 0 if the caller does not want the unmap call to
739 /// wait for any events to be signaled before performing the unmap
742 /// @param in_pDependencies
743 /// [in] An optional array of handles to previously created COIEVENT
744 /// objects that this unmap operation will wait for before starting.
745 /// This allows the user to create dependencies between asynchronous
746 /// unmap calls and other operations such as run functions or other
747 /// asynchronous unmap calls. The user may pass in NULL if they do not
748 /// wish to wait for any dependencies to complete before initiating
749 /// unmap operations.
751 /// @param out_pCompletion
752 /// [out] An optional pointer to a COIEVENT object that will be
753 /// signaled when the unmap is complete. The user may pass in NULL if
754 /// the user wants COIBufferUnmap to perform a blocking unmap
757 /// @return COI_SUCCESS upon successful unmapping of the buffer instance.
759 /// @return COI_INVALID_HANDLE if the passed in map instance handle was NULL.
761 /// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
762 /// in_NumDependencies is 0.
764 /// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
765 /// in_NumDependencies is not 0.
770 COIMAPINSTANCE in_MapInstance
,
771 uint32_t in_NumDependencies
,
772 const COIEVENT
* in_pDependencies
,
773 COIEVENT
* out_pCompletion
);
775 //////////////////////////////////////////////////////////////////////////////
777 /// Gets the Sink's virtual address of the buffer. This is the same
778 /// address that is passed to the run function on the Sink. The virtual
779 /// address assigned to the buffer for use on the sink is fixed;
780 /// the buffer will always be present at that virtual address on the sink
781 /// and will not get a different virtual address across different
783 /// This address is only valid on the Sink and should not be dereferenced on
784 /// the Source (except for the special case of buffers created with the
785 /// COI_SAME_ADDRESS flag).
788 /// [in] Buffer handle
790 /// @param out_pAddress
791 /// [out] pointer to a uint64_t* that will be filled with the address.
793 /// @return COI_SUCCESS upon successful return of the buffer's address.
795 /// @return COI_INVALID_HANDLE if the passed in buffer handle was invalid.
797 /// @return COI_INVALID_POINTER if the out_pAddress parameter was invalid.
799 /// @return COI_NOT_SUPPORTED if the buffer passed in is of type
800 /// COI_BUFFER_STREAMING_TO_SOURCE or COI_BUFFER_STREAMING_TO_SINK.
804 COIBufferGetSinkAddress(
806 uint64_t* out_pAddress
);
808 //////////////////////////////////////////////////////////////////////////////
810 /// Copy data from a normal virtual address into an existing COIBUFFER.
811 /// Note that it is not possible to use this API with any type of
812 /// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers.
813 /// Please note that COIBufferWrite does not follow implicit buffer
814 /// dependencies. If a buffer is in use in a run function or has been added
815 /// to a process using COIBufferAddRef the call to COIBufferWrite will not
816 /// wait, it will still copy data immediately.
817 /// This is to facilitate a usage model where a buffer is being used outside
818 /// of a run function, for example in a spawned thread, but data still needs
819 /// to be transferred to or from the buffer.
821 /// @param in_DestBuffer
822 /// [in] Buffer to write into.
824 #ifdef COI_PROTOTYPE_TARGET_PROCESS
825 /// @param in_DestProcess
826 /// [in] A pointer to the processes which are used as hints
827 /// to to COI. Buffers are updated upon these processes first.
828 /// Can be left NULL and default behavior will be chosen, which
829 /// chooses the lowest SCIF node with an active regions first. Others
830 /// buffer regions are invalidated in both cases. Will only update a single
831 /// process at this time.
835 /// [in] Location in the buffer to start writing to.
837 /// @param in_pSourceData
838 /// [in] A pointer to local memory that should be copied into the
842 /// [in] The number of bytes to write from in_pSourceData into
843 /// in_DestBuffer. Must not be larger than the size of in_DestBuffer
844 /// and must not over run in_DestBuffer if an in_Offset is provided.
847 /// [in] The type of copy operation to use, one of either
848 /// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
850 /// @param in_NumDependencies
851 /// [in] The number of dependencies specified in the in_pDependencies
852 /// array. This may be 0 if the caller does not want the write call to
853 /// wait for any additional events to be signaled before starting the
856 /// @param in_pDependencies
857 /// [in] An optional array of handles to previously created COIEVENT
858 /// objects that this write operation will wait for before starting.
859 /// This allows the user to create dependencies between buffer write
860 /// calls and other operations such as run functions and map calls. The
861 /// user may pass in NULL if they do not wish to wait for any
862 /// additional dependencies to complete before doing the write.
864 /// @param out_pCompletion
865 /// [out] An optional event to be signaled when the write has
866 /// completed. This event can be used as a dependency to order
867 /// the write with regard to future operations.
868 /// If no completion event is passed in then the write is
869 /// synchronous and will block until the transfer is complete.
872 /// @return COI_SUCCESS if the buffer was copied successfully.
874 /// @return COI_INVALID_HANDLE if the buffer handle was invalid.
876 /// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
878 /// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
879 /// in_NumDependencies is 0.
881 /// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
882 /// in_NumDependencies is not 0.
884 /// @return COI_NOT_SUPPORTED if the source buffer is of type
885 /// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE.
887 /// @return COI_INVALID_POINTER if the in_pSourceData pointer is NULL.
889 /// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of
892 /// @return COI_OUT_OF_RANGE if in_Length is 0.
894 /// @return COI_RETRY if in_DestBuffer is mapped and is not a COI_BUFFER_PINNED
895 /// buffer or COI_BUFFER_OPENCL buffer.
897 #ifdef COI_PROTOTYPE_TARGET_PROCESS
901 COIBUFFER in_DestBuffer
,
902 const COIPROCESS in_DestProcess
,
904 const void* in_pSourceData
,
906 COI_COPY_TYPE in_Type
,
907 uint32_t in_NumDependencies
,
908 const COIEVENT
* in_pDependencies
,
909 COIEVENT
* out_pCompletion
);
910 __asm__(".symver COIBufferWrite,COIBufferWrite@COI_2.0");
915 COIBUFFER in_DestBuffer
,
917 const void* in_pSourceData
,
919 COI_COPY_TYPE in_Type
,
920 uint32_t in_NumDependencies
,
921 const COIEVENT
* in_pDependencies
,
922 COIEVENT
* out_pCompletion
);
923 __asm__(".symver COIBufferWrite,COIBufferWrite@COI_1.0");
926 //////////////////////////////////////////////////////////////////////////////
928 /// Copy data from a buffer into local memory.
929 /// Note that it is not possible to use this API with any type of
930 /// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers.
931 /// Please note that COIBufferRead does not follow implicit buffer
932 /// dependencies. If a buffer is in use in a run function or has been added
933 /// to a process using COIBufferAddRef the call to COIBufferRead will not
934 /// wait, it will still copy data immediately.
935 /// This is to facilitate a usage model where a buffer is being used outside
936 /// of a run function, for example in a spawned thread, but data still needs
937 /// to be transferred to or from the buffer.
940 /// @param in_SourceBuffer
941 /// [in] Buffer to read from.
944 /// [in] Location in the buffer to start reading from.
946 /// @param in_pDestData
947 /// [in] A pointer to local memory that should be written into from
948 /// the provided buffer.
951 /// [in] The number of bytes to write from in_SourceBuffer into
952 /// in_pDestData. Must not be larger than the size of in_SourceBuffer
953 /// and must not over run in_SourceBuffer if an in_Offset is provided.
956 /// [in] The type of copy operation to use, one of either
957 /// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
959 /// @param in_NumDependencies
960 /// [in] The number of dependencies specified in the in_pDependencies
961 /// array. This may be 0 if the caller does not want the read call to
962 /// wait for any additional events to be signaled before starting the
965 /// @param in_pDependencies
966 /// [in] An optional array of handles to previously created COIEVENT
967 /// objects that this read operation will wait for before starting.
968 /// This allows the user to create dependencies between buffer read
969 /// calls and other operations such as run functions and map calls. The
970 /// user may pass in NULL if they do not wish to wait for any
971 /// additional dependencies to complete before doing the read.
973 /// @param out_pCompletion
974 /// [out] An optional event to be signaled when the read has
975 /// completed. This event can be used as a dependency to order
976 /// the read with regard to future operations.
977 /// If no completion event is passed in then the read is
978 /// synchronous and will block until the transfer is complete.
980 /// @return COI_SUCCESS if the buffer was copied successfully.
982 /// @return COI_INVALID_HANDLE if the buffer handle was invalid.
984 /// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
986 /// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
987 /// in_NumDependencies is 0.
989 /// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
990 /// in_NumDependencies is not 0.
992 /// @return COI_NOT_SUPPORTED if the source buffer is of type
993 /// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE.
995 /// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of
998 /// @return COI_OUT_OF_RANGE if in_Length is 0.
1000 /// @return COI_INVALID_POINTER if the in_pDestData pointer is NULL.
1002 /// @return COI_RETRY if in_SourceBuffer is mapped and is not a
1003 /// COI_BUFFER_PINNED buffer or COI_BUFFER_OPENCL buffer.
1008 COIBUFFER in_SourceBuffer
,
1012 COI_COPY_TYPE in_Type
,
1013 uint32_t in_NumDependencies
,
1014 const COIEVENT
* in_pDependencies
,
1015 COIEVENT
* out_pCompletion
);
1017 //////////////////////////////////////////////////////////////////////////////
1019 /// Copy data between two buffers. It also allows copying within the same
1020 /// buffer. For copy within the same buffer, if source and destination regions
1021 /// overlap then this API returns error.
1022 /// Note that it is not possible to use this API with any type of
1023 /// Intel® Coprocessor Offload Infrastructure (Intel® COI) Streaming Buffers.
1024 /// Please note that COIBufferCopy does not follow implicit buffer
1025 /// dependencies. If a buffer is in use in a run function or has been added
1026 /// to a process using COIBufferAddRef the call to COIBufferCopy will not
1027 /// wait, it will still copy data immediately.
1028 /// This is to facilitate a usage model where a buffer is being used outside
1029 /// of a run function, for example in a spawned thread, but data still needs
1030 /// to be transferred to or from the buffer.
1032 /// @param in_DestBuffer
1033 /// [in] Buffer to copy into.
1034 #ifdef COI_PROTOTYPE_TARGET_PROCESS
1035 /// @param in_DestProcess
1036 /// [in] A pointer to the processes which are used as hints
1037 /// to to COI. Buffers are updated upon these processes first.
1038 /// Can be left NULL and default behavior will be chosen, which
1039 /// chooses the lowest SCIF node with an active regions first. Others
1040 /// buffer regions are invalidated in both cases. Will only update a single
1041 /// process at this time.
1044 /// @param in_SourceBuffer
1045 /// [in] Buffer to copy from.
1047 /// @param in_DestOffset
1048 /// [in] Location in the destination buffer to start writing to.
1050 /// @param in_SourceOffset
1051 /// [in] Location in the source buffer to start reading from.
1053 /// @param in_Length
1054 /// [in] The number of bytes to copy from in_SourceBuffer into
1055 /// in_DestinationBuffer.
1056 /// If the length is specified as zero then length to be copied
1057 // is entire destination buffer's length.
1058 /// Must not be larger than the size of in_SourceBuffer or
1059 /// in_DestBuffer and must not over run in_SourceBuffer or
1060 /// in_DestBuffer if offsets are specified.
1063 /// [in] The type of copy operation to use, one of either
1064 /// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
1066 /// @param in_NumDependencies
1067 /// [in] The number of dependencies specified in the in_pDependencies
1068 /// array. This may be 0 if the caller does not want the copy call to
1069 /// wait for any additional events to be signaled before starting the
1072 /// @param in_pDependencies
1073 /// [in] An optional array of handles to previously created COIEVENT
1074 /// objects that this copy operation will wait for before starting.
1075 /// This allows the user to create dependencies between buffer copy
1076 /// calls and other operations such as run functions and map calls. The
1077 /// user may pass in NULL if they do not wish to wait for any
1078 /// additional dependencies to complete before doing the copy.
1080 /// @param out_pCompletion
1081 /// [out] An optional event to be signaled when the copy has
1082 /// completed. This event can be used as a dependency to order
1083 /// the copy with regard to future operations.
1084 /// If no completion event is passed in then the copy is
1085 /// synchronous and will block until the transfer is complete.
1087 /// @return COI_SUCCESS if the buffer was copied successfully.
1089 /// @return COI_INVALID_HANDLE if either buffer handle was invalid.
1091 /// @return COI_MEMORY_OVERLAP if in_SourceBuffer and in_DestBuffer are the
1092 /// same buffer(or have the same parent buffer) and the source and
1093 /// destination regions overlap
1095 /// @return COI_OUT_OF_RANGE if in_DestOffset is is beyond the end of
1098 /// @return COI_OUT_OF_RANGE if in_SourceOffset is beyond the end of
1099 /// in_SourceBuffer.
1101 /// @return COI_OUT_OF_RANGE if in_DestOffset + in_Length exceeds the size of
1102 /// the in_DestBuffer
1104 /// @return COI_OUT_OF_RANGE if in_SourceOffset + in_Length exceeds
1105 /// the size of in_SourceBuffer.
1107 /// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
1108 /// in_NumDependencies is 0.
1110 /// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
1111 /// in_NumDependencies is not 0.
1113 /// @return COI_NOT_SUPPORTED if the source or destination buffers are of type
1114 /// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE.
1116 /// @return COI_NOT_SUPPORTED if either buffer is of type
1117 /// COI_BUFFER_STREAMING_TO_SINK or COI_BUFFER_STREAMING_TO_SOURCE.
1119 /// @return COI_RETRY if in_DestBuffer or in_SourceBuffer are mapped and not
1120 /// COI_BUFFER_PINNED buffers or COI_BUFFER_OPENCL buffers.
1122 #ifdef COI_PROTOTYPE_TARGET_PROCESS
1126 COIBUFFER in_DestBuffer
,
1127 const COIPROCESS in_DestProcess
,
1128 COIBUFFER in_SourceBuffer
,
1129 uint64_t in_DestOffset
,
1130 uint64_t in_SourceOffset
,
1132 COI_COPY_TYPE in_Type
,
1133 uint32_t in_NumDependencies
,
1134 const COIEVENT
* in_pDependencies
,
1135 COIEVENT
* out_pCompletion
);
1136 __asm__(".symver COIBufferCopy,COIBufferCopy@COI_2.0");
1141 COIBUFFER in_DestBuffer
,
1142 COIBUFFER in_SourceBuffer
,
1143 uint64_t in_DestOffset
,
1144 uint64_t in_SourceOffset
,
1146 COI_COPY_TYPE in_Type
,
1147 uint32_t in_NumDependencies
,
1148 const COIEVENT
* in_pDependencies
,
1149 COIEVENT
* out_pCompletion
);
1150 __asm__(".symver COIBufferCopy,COIBufferCopy@COI_1.0");
1152 //////////////////////////////////////////////////////////////////////////////
1154 /// This API allows an experienced Intel® Coprocessor Offload Infrastructure
1155 /// (Intel® COI) developer to set where a COIBUFFER is
1156 /// located and when the COIBUFFER's data is moved. This functionality is
1157 /// useful when the developer knows when and where a buffer is going to be
1158 /// accessed. It allows the data movement to happen sooner than if the
1159 /// Intel® Coprocessor Offload Infrastructure (Intel® COI)
1160 /// runtime tried to manage the buffer placement itself. The advantage of
1161 /// this API is that the developer knows much more about their own
1162 /// application's data access patterns and can therefore optimize the data
1163 /// access to be much more efficient than the Intel® Coprocessor Offload
1164 /// Infrastructure (Intel® COI) runtime. Using this API may yield better
1165 /// memory utilization, lower latency and overall improved workload
1167 /// This API does respect implicit dependencies for buffer read/write hazards.
1168 /// For example, if the buffer is being written in one COIPROCESS and the user
1169 /// requests the buffer be placed in another COIPROCESS then this API will wait
1170 /// for the first access to complete before moving the buffer.
1171 /// This API is not required for program correctness. It is intended solely
1172 /// for advanced Intel® Coprocessor Offload Infrastructure (Intel® COI)
1173 /// developers who wish to fine tune their application performance
1174 /// Cases where "a change in state" is an error condition the change just gets
1175 /// ignored without any error. This is because the SetState can be a
1176 /// nonblocking call and in such cases we can't rely on the state of the buffer
1177 /// at the time of the call. We can do the transition checks only at the time
1178 /// when the actual state change happens (which is something in future).
1179 /// Currently there is no way to report an error from something that happens in
1180 /// future and that is why such state transitions are nop. One example is using
1181 /// VALID_MAY_DROP with COI_SINK_OWNERS when buffer is not valid at source.
1182 /// This operation will be a nop if at the time of actual state change the
1183 /// buffer is not valid at source.
1185 /// @param in_Buffer
1186 /// [in] The buffer to modify.
1188 /// @param in_Process
1189 /// [in] The process where the state is being modified for this
1190 /// buffer. To modify buffer's state on source process use
1191 /// COI_PROCESS_SOURCE as process handle. To modify buffer's
1192 /// state on all processes where buffer is valid use COI_SINK_OWNERS
1193 /// as the process handle.
1196 /// [in] The new state for the buffer. The buffer's state could be
1197 /// set to invalid on one of the sink processes where it is being
1200 /// @param in_DataMove
1201 /// [in] A flag to indicate if the buffer's data should be moved
1202 /// when the state is changed. For instance, a buffer's state may
1203 /// be set to valid on a process and the data move flag may be set to
1204 /// COI_BUFFER_MOVE which would cause the buffer contents to be
1205 /// copied to the process where it is now valid.
1207 /// @param in_NumDependencies
1208 /// [in] The number of dependencies specified in the in_pDependencies
1209 /// array. This may be 0 if the caller does not want the SetState call
1210 /// to wait for any additional events to be signaled before starting
1213 /// @param in_pDependencies
1214 /// [in] An optional array of handles to previously created COIEVENT
1215 /// objects that this SetState operation will wait for before starting
1216 /// This allows the user to create dependencies between buffer
1217 /// SetState calls and other operations such as run functions and map
1218 /// calls. The user may pass in NULL if they do not wish to wait for
1219 /// any additional dependencies to complete before doing the SetState
1221 /// @param out_pCompletion
1222 /// [out] An optional event to be signaled when the SetState has
1223 /// completed. This event can be used as a dependency to order
1224 /// the SetState with regard to future operations.
1225 /// If no completion event is passed in then the is
1226 /// synchronous and will block until the SetState and dma transfers
1227 /// related to this operation are complete.
1229 /// @return COI_SUCCESS if the buffer's state was changed successfully.
1231 /// @return COI_INVALID_HANDLE if in_Buffer or in_Process is invalid.
1233 /// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than
1234 /// COI_BUFFER_NORMAL or COI_BUFFER_OPENCL.
1236 /// @return COI_ARGUMENT_MISMATCH if the in_State is COI_BUFFER_VALID_MAY_DROP
1237 /// and the in_Process is COI_PROCESS_SOURCE.
1239 /// @return COI_ARGUMENT_MISMATCH if the in_Process is COI_SINK_OWNERS and the
1240 /// COI_BUFFER_MOVE is passed as move flag.
1242 /// @return COI_MISSING_DEPENDENCY if buffer was not created on the process
1243 /// handle that was passed in.
1249 COIBUFFER in_Buffer
,
1250 COIPROCESS in_Process
,
1251 COI_BUFFER_STATE in_State
,
1252 COI_BUFFER_MOVE_FLAG in_DataMove
,
1253 uint32_t in_NumDependencies
,
1254 const COIEVENT
* in_pDependencies
,
1255 COIEVENT
* out_pCompletion
);
1257 //////////////////////////////////////////////////////////////////////////////
1259 /// Creates a sub-buffer that is a reference to a portion of an existing
1260 /// buffer. The returned buffer handle can be used in all API calls that the
1261 /// original buffer handle could be used in except COIBufferCreateSubBuffer.
1262 /// Sub buffers out of Huge Page Buffer are also supported but the original
1263 /// buffer needs to be a OPENCL buffer created with COI_OPTIMIZE_HUGE_PAGE_SIZE
1266 /// When the sub-buffer is used only the corresponding sub-section of the
1267 /// original buffer is used or affected.
1269 /// @param in_Buffer
1270 /// [in] The original buffer that this new sub-buffer is a reference
1273 /// @param in_Length
1274 /// [in] The length of the sub-buffer in number of bytes.
1276 /// @param in_Offset
1277 /// [in] Where in the original buffer to start this sub-buffer.
1279 /// @param out_pSubBuffer
1280 /// [out] Pointer to a buffer handle that is filled in with the newly
1281 /// created sub-buffer.
1283 /// @return COI_SUCCESS if the sub-buffer was created
1285 /// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle.
1287 /// @return COI_OUT_OF_RANGE if in_Length is zero, or if in_Offset + in_Length
1288 /// is greater than the size of the original buffer.
1290 /// @return COI_OUT_OF_MEMORY if allocating the buffer fails.
1292 /// @return COI_INVALID_POINTER if the out_pSubBuffer pointer is NULL.
1294 /// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than
1295 /// COI_BUFFER_OPENCL
1299 COIBufferCreateSubBuffer(
1300 COIBUFFER in_Buffer
,
1303 COIBUFFER
* out_pSubBuffer
);
1309 #endif /* _COIBUFFER_SOURCE_H */