2015-08-28 15:33:40 +00:00
|
|
|
|
/*
|
2017-04-10 11:32:00 +00:00
|
|
|
|
* Copyright 2010-2015 Intel Corporation.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
*
|
|
|
|
|
* This library is free software; you can redistribute it and/or modify it
|
|
|
|
|
* under the terms of the GNU Lesser General Public License as published
|
|
|
|
|
* by the Free Software Foundation, version 2.1.
|
|
|
|
|
*
|
|
|
|
|
* This library is distributed in the hope that it will be useful,
|
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
|
|
|
* License along with this library; if not, write to the Free Software
|
|
|
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
|
|
|
* 02110-1301 USA.
|
|
|
|
|
*
|
|
|
|
|
* Disclaimer: The codes contained in these modules may be specific
|
|
|
|
|
* to the Intel Software Development Platform codenamed Knights Ferry,
|
|
|
|
|
* and the Intel product codenamed Knights Corner, and are not backward
|
|
|
|
|
* compatible with other Intel products. Additionally, Intel will NOT
|
|
|
|
|
* support the codes or instruction set in future products.
|
|
|
|
|
*
|
|
|
|
|
* Intel offers no warranty of any kind regarding the code. This code is
|
|
|
|
|
* licensed on an "AS IS" basis and Intel is not obligated to provide
|
|
|
|
|
* any support, assistance, installation, training, or other services
|
|
|
|
|
* of any kind. Intel is also not obligated to provide any updates,
|
|
|
|
|
* enhancements or extensions. Intel specifically disclaims any warranty
|
|
|
|
|
* of merchantability, non-infringement, fitness for any particular
|
|
|
|
|
* purpose, and any other warranty.
|
|
|
|
|
*
|
|
|
|
|
* Further, Intel disclaims all liability of any kind, including but
|
|
|
|
|
* not limited to liability for infringement of any proprietary rights,
|
|
|
|
|
* relating to the use of the code, even if Intel is notified of the
|
|
|
|
|
* possibility of such liability. Except as expressly stated in an Intel
|
|
|
|
|
* license agreement provided with this code and agreed upon with Intel,
|
|
|
|
|
* no license, express or implied, by estoppel or otherwise, to any
|
|
|
|
|
* intellectual property rights is granted herein.
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
#ifndef _COIBUFFER_SOURCE_H
|
|
|
|
|
#define _COIBUFFER_SOURCE_H
|
|
|
|
|
|
|
|
|
|
/** @ingroup COIBuffer
|
|
|
|
|
* @addtogroup COIBufferSource
|
|
|
|
|
@{
|
|
|
|
|
|
|
|
|
|
* @file source\COIBuffer_source.h
|
|
|
|
|
*/
|
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
|
#include "../common/COITypes_common.h"
|
|
|
|
|
#include "../common/COIResult_common.h"
|
|
|
|
|
#endif // DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
|
|
|
|
|
|
#ifdef __cplusplus
|
|
|
|
|
extern "C" {
|
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
///////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
/// The valid buffer types that may be created using COIBufferCreate.
|
|
|
|
|
/// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix
|
|
|
|
|
/// below which describes the valid combinations of buffer types and flags.
|
|
|
|
|
///
|
|
|
|
|
typedef enum COI_BUFFER_TYPE
|
|
|
|
|
{
|
|
|
|
|
/// Normal buffers exist as a single physical buffer in either Source or
|
|
|
|
|
/// Sink physical memory. Mapping the buffer may stall the pipelines.
|
|
|
|
|
COI_BUFFER_NORMAL = 1,
|
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
|
// Reserved values, not used by COI any more
|
|
|
|
|
COI_BUFFER_RESERVED_1,
|
|
|
|
|
COI_BUFFER_RESERVED_2,
|
2015-08-28 15:33:40 +00:00
|
|
|
|
|
|
|
|
|
/// A pinned buffer exists in a shared memory region and is always
|
|
|
|
|
/// available for read or write operations.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Note: Pinned Buffers larger than 4KB are not supported in
|
|
|
|
|
/// Windows 7 kernels.
|
|
|
|
|
/// The value of COI_BUFFER_PINNED is set to specific value
|
|
|
|
|
/// to maintain compatibility with older versions of COI
|
2015-08-28 15:33:40 +00:00
|
|
|
|
COI_BUFFER_PINNED,
|
|
|
|
|
|
|
|
|
|
/// OpenCL buffers are similar to Normal buffers except they don't
|
|
|
|
|
/// stall pipelines and don't follow any read write dependencies.
|
|
|
|
|
COI_BUFFER_OPENCL
|
|
|
|
|
|
|
|
|
|
} COI_BUFFER_TYPE;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/// @name COIBUFFER creation flags.
|
|
|
|
|
/// Please see the COI_VALID_BUFFER_TYPES_AND_FLAGS matrix
|
|
|
|
|
/// below which describes the valid combinations of buffer types and flags.
|
|
|
|
|
//@{
|
|
|
|
|
|
|
|
|
|
/// Create the buffer such that it has the same virtual address on all of the
|
|
|
|
|
/// sink processes with which it is associated.
|
|
|
|
|
#define COI_SAME_ADDRESS_SINKS 0x00000001
|
|
|
|
|
|
|
|
|
|
/// Create the buffer such that it has the same virtual address on all of the
|
|
|
|
|
/// sink processes with which it is associated and in the source process.
|
|
|
|
|
#define COI_SAME_ADDRESS_SINKS_AND_SOURCE 0x00000002
|
|
|
|
|
|
|
|
|
|
/// Hint to the runtime that the source will frequently read the buffer
|
|
|
|
|
#define COI_OPTIMIZE_SOURCE_READ 0x00000004
|
|
|
|
|
|
|
|
|
|
/// Hint to the runtime that the source will frequently write the buffer
|
|
|
|
|
#define COI_OPTIMIZE_SOURCE_WRITE 0x00000008
|
|
|
|
|
|
|
|
|
|
/// Hint to the runtime that the sink will frequently read the buffer
|
|
|
|
|
#define COI_OPTIMIZE_SINK_READ 0x00000010
|
|
|
|
|
|
|
|
|
|
/// Hint to the runtime that the sink will frequently write the buffer
|
|
|
|
|
#define COI_OPTIMIZE_SINK_WRITE 0x00000020
|
|
|
|
|
|
|
|
|
|
/// Used to delay the pinning of memory into physical pages, until required
|
|
|
|
|
/// for DMA. This can be used to delay the cost of time spent pinning memory
|
|
|
|
|
/// until absolutely necessary. Might speed up the execution of COIBufferCreate
|
|
|
|
|
/// calls, but slow down the first access of the buffer in
|
|
|
|
|
/// COIPipelineRunFunction(s) or other COIBuffer access API's.
|
|
|
|
|
/// Also of important note, that with this flag enabled COI will not be able to
|
|
|
|
|
/// check to see if this memory is read only. Ordinarily this is checked
|
|
|
|
|
/// and an error is thrown upon buffer creation. With this flag, the error
|
|
|
|
|
/// might occur later, and cause undetermined behavior. Be sure to always
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// use writable memory for COIBuffers.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
#define COI_OPTIMIZE_NO_DMA 0x00000040
|
|
|
|
|
|
|
|
|
|
/// Hint to the runtime to try to use huge page sizes for backing store on the
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// sink. Is currently not compatible with PINNED buffers or the SAME_ADDRESS
|
|
|
|
|
/// flags or the SINK_MEMORY flag. It is important to note that this is a hint
|
|
|
|
|
/// and internally the runtime may not actually promote to huge pages.
|
|
|
|
|
/// Specifically if the buffer is too small (less than 4KiB for example) then
|
|
|
|
|
/// the runtime will not promote the buffer to use huge pages.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
#define COI_OPTIMIZE_HUGE_PAGE_SIZE 0x00000080
|
|
|
|
|
|
|
|
|
|
/// Used to tell Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
|
|
|
|
/// to create a buffer using memory that has already been
|
|
|
|
|
/// allocated on the sink. This flag is only valid when passed in to the
|
|
|
|
|
/// COIBufferCreateFromMemory API.
|
|
|
|
|
#define COI_SINK_MEMORY 0x00000100
|
|
|
|
|
|
|
|
|
|
//@}
|
|
|
|
|
|
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
|
// Make the flag mask
|
|
|
|
|
#ifdef F
|
|
|
|
|
#undef F
|
|
|
|
|
#endif
|
|
|
|
|
#define F 0
|
|
|
|
|
#ifdef T
|
|
|
|
|
#undef T
|
|
|
|
|
#endif
|
|
|
|
|
#define T 1
|
|
|
|
|
#define MTM(_BUFFER, B1, B2, B3, B4, B5, B6, B7, B8, B9) \
|
|
|
|
|
(B1 | B2<<1 | B3<<2 | B4<<3 | B5<<4 | B6<<5 | B7<<6 | B8<<7 | B9<<8)
|
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
/// \enum COI_BUFFER_TYPE
|
|
|
|
|
/// This matrix shows the valid combinations of buffer types and buffer flags
|
|
|
|
|
/// that may be passed in to COIBufferCreate and COIBufferCreateFromMemory.
|
|
|
|
|
/// \code
|
|
|
|
|
static const uint64_t
|
|
|
|
|
COI_VALID_BUFFER_TYPES_AND_FLAGS[COI_BUFFER_OPENCL+1] = {
|
|
|
|
|
/* | | SAME | | | | | | | |
|
|
|
|
|
| SAME | ADDR | OPT | OPT | OPT | OPT | OPT | HUGE | COI |
|
|
|
|
|
| ADDR | SINK | SRC | SRC | SINK | SINK | NO | PAGE | SINK |
|
|
|
|
|
| SINKS | SRC | READ | WRITE | READ | WRITE | DMA | SIZE | MEM |
|
|
|
|
|
+-------+------+------+-------+------+-------+-----+------+-----*/
|
2017-04-10 11:32:00 +00:00
|
|
|
|
MTM(INVALID , F , F , F , F , F , F , F , F , F ),
|
|
|
|
|
MTM(NORMAL , T , T , T , T , T , T , T , T , T ),
|
|
|
|
|
MTM(RESERVED1 , F , F , F , F , F , F , F , F , F ),
|
|
|
|
|
MTM(RESERVED2 , F , F , F , F , F , F , F , F , F ),
|
|
|
|
|
MTM(PINNED , T , T , T , T , T , T , F , F , F ),
|
|
|
|
|
MTM(OPENCL , T , T , T , T , T , T , T , T , F ),
|
2015-08-28 15:33:40 +00:00
|
|
|
|
};
|
|
|
|
|
///\endcode
|
|
|
|
|
#undef MTM
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
/// These flags control how the buffer will be accessed on the source after
|
|
|
|
|
/// it is mapped.
|
|
|
|
|
/// Please see the COI_VALID_BUFFER_TYPES_AND_MAP matrix below for the
|
|
|
|
|
/// valid buffer type and map operation combinations.
|
|
|
|
|
typedef enum COI_MAP_TYPE
|
|
|
|
|
{
|
|
|
|
|
/// Allows the application to read and write the contents of the buffer
|
|
|
|
|
/// after it is mapped.
|
|
|
|
|
COI_MAP_READ_WRITE = 1,
|
|
|
|
|
|
|
|
|
|
/// If this flag is set then the application must only read from the
|
|
|
|
|
/// buffer after it is mapped. If the application writes to the buffer
|
|
|
|
|
/// the contents will not be reflected back to the sink or stored for
|
|
|
|
|
/// the next time the buffer is mapped on the source.
|
|
|
|
|
/// This allows the runtime to make significant performance optimizations
|
|
|
|
|
/// in buffer handling.
|
|
|
|
|
COI_MAP_READ_ONLY,
|
|
|
|
|
|
|
|
|
|
/// Setting this flag means that the source will overwrite the entire
|
|
|
|
|
/// buffer once it is mapped. The app must not read from the buffer and
|
|
|
|
|
/// must not expect the contents of the buffer to be synchronized from
|
|
|
|
|
/// the sink side during the map operation.
|
|
|
|
|
/// This allows the runtime to make significant performance optimizations
|
|
|
|
|
/// in buffer handling.
|
|
|
|
|
COI_MAP_WRITE_ENTIRE_BUFFER
|
|
|
|
|
} COI_MAP_TYPE;
|
|
|
|
|
|
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
|
// Make the flag mask
|
|
|
|
|
#define MMM(_BUFFER, B1, B2, B3) \
|
|
|
|
|
{ F , B1, B2, B3}
|
|
|
|
|
#endif
|
|
|
|
|
/// \enum COI_MAP_TYPE
|
|
|
|
|
/// This matrix shows the valid combinations of buffer types and map
|
|
|
|
|
/// operations that may be passed in to COIBufferMap.
|
|
|
|
|
/// \code
|
|
|
|
|
static const uint64_t
|
|
|
|
|
COI_VALID_BUFFER_TYPES_AND_MAP
|
|
|
|
|
[COI_BUFFER_OPENCL+1][COI_MAP_WRITE_ENTIRE_BUFFER+1] = {
|
|
|
|
|
/* | MAP | MAP | MAP |
|
|
|
|
|
| READ | READ | WRITE |
|
|
|
|
|
| WRITE | ONLY | ENTIRE|
|
|
|
|
|
+-------+-------+-------+*/
|
|
|
|
|
MMM(INVALID , F , F , F ),
|
|
|
|
|
MMM(NORMAL , T , T , T ),
|
2017-04-10 11:32:00 +00:00
|
|
|
|
MMM(RESERVED1 , F , F , F ),
|
|
|
|
|
MMM(RESERVED2 , F , F , F ),
|
2015-08-28 15:33:40 +00:00
|
|
|
|
MMM(PINNED , T , T , T ),
|
|
|
|
|
MMM(OPENCL , T , T , T ),
|
|
|
|
|
};
|
|
|
|
|
///\endcode
|
|
|
|
|
#undef MMM
|
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
|
#undef F
|
|
|
|
|
#undef T
|
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
/// The valid copy operation types for the COIBufferWrite, COIBufferRead,
|
|
|
|
|
/// and COIBufferCopy APIs.
|
|
|
|
|
///
|
|
|
|
|
typedef enum COI_COPY_TYPE
|
|
|
|
|
{
|
|
|
|
|
/// The runtime can pick the best suitable way to copy the data.
|
|
|
|
|
COI_COPY_UNSPECIFIED = 0,
|
|
|
|
|
|
|
|
|
|
/// The runtime should use DMA to copy the data.
|
|
|
|
|
COI_COPY_USE_DMA,
|
|
|
|
|
|
|
|
|
|
/// The runtime should use a CPU copy to copy the data.
|
|
|
|
|
/// CPU copy is a synchronous copy. So the resulting operations are always
|
|
|
|
|
/// blocking (even though a out_pCompletion event is specified).
|
2017-04-10 11:32:00 +00:00
|
|
|
|
COI_COPY_USE_CPU,
|
|
|
|
|
|
|
|
|
|
/// Same as above, but forces moving entire buffer to target process in Ex
|
|
|
|
|
/// extended APIs, even if the full buffer is not written.
|
|
|
|
|
COI_COPY_UNSPECIFIED_MOVE_ENTIRE,
|
|
|
|
|
|
|
|
|
|
/// Same as above, but forces moving entire buffer to target process in Ex
|
|
|
|
|
/// extended APIs, even if the full buffer is not written.
|
|
|
|
|
COI_COPY_USE_DMA_MOVE_ENTIRE,
|
|
|
|
|
|
|
|
|
|
/// Same as above, but forces moving entire buffer to target process in Ex
|
|
|
|
|
/// extended APIs, even if the full buffer is not written.
|
|
|
|
|
COI_COPY_USE_CPU_MOVE_ENTIRE
|
2015-08-28 15:33:40 +00:00
|
|
|
|
|
|
|
|
|
} COI_COPY_TYPE;
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
/// The buffer states are used to indicate whether a buffer is available for
|
|
|
|
|
/// access in a COIPROCESS. This is used with COIBufferSetState.
|
|
|
|
|
///
|
|
|
|
|
/// Buffer state holds only for NORMAL Buffers and OPENCL buffers. Pinned
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// buffers are always valid everywhere they get created.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// Rules on State Transition of the buffer:
|
|
|
|
|
/// -. When a Buffer is created by default it is valid only on the source,
|
|
|
|
|
/// except for buffers created with COI_SINK_MEMORY flag which are valid
|
|
|
|
|
/// only on the sink where the memory lies when created.
|
|
|
|
|
/// -. Apart from SetState following APIs also alters the state of the buffer
|
|
|
|
|
/// internally:
|
|
|
|
|
///
|
|
|
|
|
/// - COIBufferMap alters state of buffer depending on the COI_MAP_TYPE.
|
|
|
|
|
/// COI_MAP_READ_ONLY: Makes Valid on the Source. Doesn't affect the state
|
|
|
|
|
/// of the buffer on the other devices.
|
|
|
|
|
/// COI_MAP_READ_WRITE: Makes it Valid only the Source and Invalid
|
|
|
|
|
/// everywhere else. OPENCL buffers are invalidated
|
|
|
|
|
/// only if it is not in use.
|
|
|
|
|
/// COI_MAP_WRITE_ENTIRE_BUFFER: Makes it valid only on the Source. OPENCL
|
|
|
|
|
/// buffers are invalidated only if not in use.
|
|
|
|
|
///
|
|
|
|
|
/// - COIPipelineRunfunction alters the state of the buffer depending on the
|
|
|
|
|
/// COI_ACCESS_FLAGS
|
|
|
|
|
/// COI_SINK_READ: Makes it valid on the sink where RunFunction is being
|
|
|
|
|
/// issued. Doesn't affect the state of the buffer on other
|
|
|
|
|
/// devices.
|
|
|
|
|
/// COI_SINK_WRITE: Makes it valid only on the sink where Runfunction is
|
|
|
|
|
/// being issued and invalid everywhere else. OPENCL
|
|
|
|
|
/// buffers are invalidated only if the buffer is not in
|
|
|
|
|
/// use.
|
|
|
|
|
/// COI_SINK_WRITE_ENTIRE: Makes it valid only on the sink where
|
|
|
|
|
/// Runfunction is being issued and invalid everywhere else
|
|
|
|
|
/// OPENCL buffers are invalidated only if the buffer is
|
|
|
|
|
/// not in use.
|
|
|
|
|
///
|
|
|
|
|
/// - COIBufferWrite makes the buffer exclusively valid where the write
|
|
|
|
|
/// happens. Write gives preference to Source over Sink. In other words
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// if a buffer is valid on the Source and multiple Sinks, Write will
|
|
|
|
|
/// happen on the Source and will Invalidate all other Sinks. If the
|
|
|
|
|
/// buffer is valid on multiple Sinks ( and not on the Source) then
|
|
|
|
|
/// Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
|
|
|
|
/// selects process handle with the lowest numerical value to do the
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// exclusive write Again, OPENCL buffers are invalidated only if the
|
|
|
|
|
/// buffer is not in use on that SINK/SOURCE.
|
|
|
|
|
///
|
|
|
|
|
/// The preference rule mentioned above holds true even for SetState API,
|
|
|
|
|
/// when data needs to be moved from a valid location. The selection of
|
|
|
|
|
/// valid location happens as stated above.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// - It is possible to alter only parts of the buffer and change it state
|
|
|
|
|
/// In other words it is possible for different parts of the buffer to have
|
|
|
|
|
/// different states on different devices. A byte is the minimum size at
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// which state can be maintained internally. Granularity level is completely
|
|
|
|
|
/// determined by how the buffer gets fragmented.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Note: Buffer is considered 'in use' if is
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// - Being used in RunFunction : In use on a Sink
|
|
|
|
|
/// - Mapped: In use on a Source
|
|
|
|
|
/// - AddRef'd: In use on Sink
|
|
|
|
|
///
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// The buffer states used with COIBufferSetState call to indicate the new
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// state of the buffer on a given process
|
|
|
|
|
///
|
|
|
|
|
typedef enum {
|
|
|
|
|
COI_BUFFER_VALID = 0, // Buffer is valid and up-to-date on the process
|
|
|
|
|
COI_BUFFER_INVALID , // Buffer is not valid, need valid data
|
|
|
|
|
COI_BUFFER_VALID_MAY_DROP, // Same as valid but will drop the content when
|
2017-04-10 11:32:00 +00:00
|
|
|
|
// evicted to avoid overwriting the shadow
|
2015-08-28 15:33:40 +00:00
|
|
|
|
// memory
|
|
|
|
|
COI_BUFFER_RESERVED // Reserved for internal use
|
|
|
|
|
} COI_BUFFER_STATE;
|
|
|
|
|
///
|
|
|
|
|
/// Note: A VALID_MAY_DROP declares a buffer's copy as secondary on a given
|
|
|
|
|
/// process. This means that there needs to be at least one primary copy of the
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// the buffer somewhere in order to mark the buffer as VALID_MAY_DROP on a
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// process. In other words to make a buffer VALID_MAY_DROP on a given process
|
|
|
|
|
/// it needs to be in COI_BUFFER_VALID state somewhere else. The operation gets
|
|
|
|
|
/// ignored (or is a nop) if there is no primary copy of the buffer. The nature
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// of this state to "drop the content" when evicted is a side effect of
|
|
|
|
|
/// marking the buffer as secondary copy. So when a buffer marked
|
|
|
|
|
/// VALID_MAY_DROP is evicted Intel(R) Coprocessor Offload Infrastructure
|
|
|
|
|
/// (Intel(R) COI) doesn't back it up as it is assumed that
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// there is a primary copy somewhere.
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
/// The buffer move flags are used to indicate when a buffer should be moved
|
|
|
|
|
/// when it's state is changed. This is used with COIBufferSetState.
|
|
|
|
|
typedef enum {
|
|
|
|
|
COI_BUFFER_MOVE = 0,// Dirty data is moved if state change requires it
|
|
|
|
|
COI_BUFFER_NO_MOVE // Change state without moving data
|
|
|
|
|
} COI_BUFFER_MOVE_FLAG;
|
|
|
|
|
|
|
|
|
|
// A process handle for COIBufferSetState call to indicate all the sink
|
|
|
|
|
// processes where the given buffer is valid
|
2017-04-10 11:32:00 +00:00
|
|
|
|
#define COI_SINK_OWNERS ((COIPROCESS)-2)
|
|
|
|
|
|
|
|
|
|
// Matrix descriptors used with MultiD Read/Write
|
|
|
|
|
typedef struct dim_desc {
|
|
|
|
|
int64_t size; // Size of data type
|
|
|
|
|
int64_t lindex; // Lower index, used in Fortran
|
|
|
|
|
int64_t lower; // Lower section bound
|
|
|
|
|
int64_t upper; // Upper section bound
|
|
|
|
|
int64_t stride; // Stride, or number of bytes between the start
|
|
|
|
|
// of one element and start of next one divided
|
|
|
|
|
// by size.
|
|
|
|
|
} dim_desc;
|
|
|
|
|
|
|
|
|
|
typedef struct arr_desc {
|
|
|
|
|
int64_t base; // Base address
|
|
|
|
|
int64_t rank; // Rank of array, i.e. number of dimensions
|
|
|
|
|
dim_desc dim[3]; // This array has as many elements as <20>rank<6E>
|
|
|
|
|
// currently limited to 3.
|
|
|
|
|
} arr_desc;
|
2015-08-28 15:33:40 +00:00
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Creates a buffer that can be used in RunFunctions that are queued in
|
|
|
|
|
/// pipelines. The address space for the buffer is reserved when it is
|
|
|
|
|
/// created although the memory may not be committed until the buffer is
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// used for the first time. Please note that the Intel(R) Coprocessor Offload
|
|
|
|
|
/// Infrastructure (Intel(R) COI) runtime may also allocate space for the
|
|
|
|
|
/// source process to use as shadow memory for certain types of buffers.
|
|
|
|
|
/// If Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
|
|
|
|
/// does allocate this memory it will not be released or reallocated
|
|
|
|
|
/// until the COIBuffer is destroyed.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_Size
|
|
|
|
|
/// [in] The number of bytes to allocate for the buffer. If in_Size
|
|
|
|
|
/// is not page aligned, it will be rounded up.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of the buffer to create.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Flags
|
|
|
|
|
/// [in] A bitmask of attributes for the newly created buffer.
|
|
|
|
|
/// Some of these flags are required for correctness while others
|
|
|
|
|
/// are provided as hints to the runtime system so it can make
|
|
|
|
|
/// certain performance optimizations.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pInitData
|
|
|
|
|
/// [in] If non-NULL the buffer will be initialized with the data
|
|
|
|
|
/// pointed to by pInitData. The memory at in_pInitData must hold
|
|
|
|
|
/// at least in_Size bytes.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumProcesses
|
|
|
|
|
/// [in] The number of processes with which this buffer might be used.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pProcesses
|
|
|
|
|
/// [in] An array of COIPROCESS handles identifying the processes with
|
|
|
|
|
/// which this buffer might be used.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pBuffer
|
|
|
|
|
/// [out] Pointer to a buffer handle. The handle will be filled in
|
|
|
|
|
/// with a value that uniquely identifies the newly created buffer.
|
|
|
|
|
/// This handle should be disposed of via COIBufferDestroy()
|
|
|
|
|
/// once it is no longer needed.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was created
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters
|
|
|
|
|
/// are not compatible with one another. Please see the
|
|
|
|
|
/// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about
|
|
|
|
|
/// which flags and types are compatible.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// the in_Flags parameter are not recognized flags, or if in_NumProcesses is zero.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the in_pProcesses or out_pBuffer parameter
|
|
|
|
|
/// is NULL.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @return COI_NOT_SUPPORTED if in_Type has invalid value or if
|
|
|
|
|
/// one of the in_Flags is COI_SINK_MEMORY.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if the flags include either
|
|
|
|
|
/// COI_SAME_ADDRESS_SINKS or COI_SAME_ADDRESS_SINKS_AND_SOURCE and
|
|
|
|
|
/// COI_OPTIMIZE_HUGE_PAGE_SIZE.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the
|
|
|
|
|
/// in_pProcesses array does not identify a valid process.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_MEMORY if allocating the buffer fails.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @return COI_RESOURCE_EXHAUSTED if the sink is out of buffer memory. This
|
|
|
|
|
/// error can also be thrown from Windows 7 operating systems if
|
|
|
|
|
/// COI_BUFFER_PINNED and a size larger than 4KB is requested.
|
|
|
|
|
/// This is due to a limitation of the Windows 7 memory management unit.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferCreate(
|
|
|
|
|
uint64_t in_Size,
|
|
|
|
|
COI_BUFFER_TYPE in_Type,
|
|
|
|
|
uint32_t in_Flags,
|
|
|
|
|
const void* in_pInitData,
|
|
|
|
|
uint32_t in_NumProcesses,
|
|
|
|
|
const COIPROCESS* in_pProcesses,
|
|
|
|
|
COIBUFFER* out_pBuffer);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Creates a buffer from some existing memory that can be used in
|
|
|
|
|
/// RunFunctions that are queued in pipelines. If the flag COI_SINK_MEMORY
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// is specified then Intel(R) Coprocessor Offload
|
|
|
|
|
/// Infrastructure (Intel(R) COI) will use that memory for the buffer on the sink.
|
|
|
|
|
/// If that flag isn't set then the memory provided is used as backing store
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// for the buffer on the source. In either case the memory must not be freed
|
|
|
|
|
/// before the buffer is destroyed.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// While the user still owns the memory passed in they must use the
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// appropriate access flags when accessing the buffer in COIPipelinRunFunction
|
|
|
|
|
/// or COIBufferMap calls so that the runtime knows when the
|
|
|
|
|
/// memory has been modified. If the user just writes directly to the memory
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// location then those changes may not be visible when the corresponding
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// buffer is accessed.
|
|
|
|
|
/// Whatever values are already present in the memory location when this call
|
|
|
|
|
/// is made are preserved. The memory values are also preserved when
|
|
|
|
|
/// COIBufferDestroy is called.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @warning: Use of this function is highly discouraged if the calling
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// program forks at all (including calls to system(3), popen(3), or similar
|
|
|
|
|
/// functions) during the life of this buffer. See the discussion around the
|
|
|
|
|
/// in_Memory parameter below regarding this.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Size
|
|
|
|
|
/// [in] The size of in_Memory in bytes. If in_Size
|
|
|
|
|
/// is not page aligned, it will be rounded up.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// [in] The type of the buffer to create. Only COI_BUFFER_NORMAL and
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// COI_BUFFER_PINNED buffer types are supported.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Flags
|
|
|
|
|
/// [in] A bitmask of attributes for the newly created buffer.
|
|
|
|
|
/// Some of these flags are required for correctness while others
|
|
|
|
|
/// are provided as hints to the runtime system so it can make
|
|
|
|
|
/// certain performance optimizations. Note that the flag
|
|
|
|
|
/// COI_SAME_ADDRESS_SINKS_AND_SOURCE is still valid but may fail
|
|
|
|
|
/// if the same address as in_Memory can not be allocated on the sink.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Memory
|
|
|
|
|
/// [in] A pointer to an already allocated memory region
|
|
|
|
|
/// that should be turned into a COIBUFFER. Although the user still
|
|
|
|
|
/// owns this memory they should not free it before calling
|
|
|
|
|
/// COIBufferDestroy. They must also only access the memory using
|
|
|
|
|
/// COIBUFFER semantics, for example using COIBufferMap/COIBufferUnmap
|
|
|
|
|
/// when they wish to read or write the data. There are no alignment
|
|
|
|
|
/// or size requirements for this memory region.
|
|
|
|
|
///
|
|
|
|
|
/// WARNING:
|
|
|
|
|
/// Since the backing memory passed in can be the target of a DMA
|
|
|
|
|
/// the caller must ensure that there is no call to clone(2) (without
|
|
|
|
|
/// the CLONE_VM argument) during the life of this buffer. This
|
|
|
|
|
/// includes higher level functions that call clone such as fork(2),
|
|
|
|
|
/// system(3), popen(3), among others).
|
|
|
|
|
///
|
|
|
|
|
/// For forked processes, Linux uses copy-on-write semantics for
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// performance reasons. Consequently, if the parent forks and then
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// writes to this memory, the physical page mapping changes causing
|
|
|
|
|
/// the DMA to fail (and thus data corruption).
|
|
|
|
|
///
|
|
|
|
|
/// In Linux you can mark a set of pages to not be copied across
|
|
|
|
|
/// across the clone by calling madvise(2) with an argument of
|
|
|
|
|
/// MADV_DONTFORK and then safely use that memory in this scenario.
|
|
|
|
|
/// Alternately, if the memory is from a region marked MAP_SHARED,
|
|
|
|
|
/// this will work.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumProcesses
|
|
|
|
|
/// [in] The number of processes with which this buffer might be used.
|
|
|
|
|
/// If the flag COI_SINK_MEMORY is specified then this must be 1.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pProcesses
|
|
|
|
|
/// [in] An array of COIPROCESS handles identifying the processes with
|
|
|
|
|
/// which this buffer might be used.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pBuffer
|
|
|
|
|
/// [out] Pointer to a buffer handle. The handle will be filled in
|
|
|
|
|
/// with a value that uniquely identifies the newly created buffer.
|
|
|
|
|
/// This handle should be disposed of via COIBufferDestroy()
|
|
|
|
|
/// once it is no longer needed.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was created
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @return COI_NOT_SUPPORTED if the in_Type value is not COI_BUFFER_NORMAL,
|
|
|
|
|
/// COI_BUFFER_PINNED, or COI_BUFFER_OPENCL.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if in_Memory is read-only memory
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if one of the in_Flags is COI_SINK_MEMORY and
|
|
|
|
|
/// in_Type is not COI_BUFFER_NORMAL
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS is set
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if the flag COI_SAME_ADDRESS_SINKS_AND_SOURCE is
|
|
|
|
|
/// set
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_Type and in_Flags parameters
|
|
|
|
|
/// are not compatible with one another. Please see the
|
|
|
|
|
/// COI_VALID_BUFFER_TYPES_AND_FLAGS map above for information about
|
|
|
|
|
/// which flags and types are compatible.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the flag COI_SINK_MEMORY is specified and
|
|
|
|
|
/// in_NumProcesses > 1.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the flags COI_SINK_MEMORY and
|
|
|
|
|
/// COI_OPTIMIZE_HUGE_PAGE_SIZE are both set.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Size is zero, if the bits set in
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// the in_Flags parameter are not recognized flags, or if in_NumProcesses is zero.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if in_Memory, in_pProcesses or
|
|
|
|
|
/// out_pBuffer parameter is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if one of the COIPROCESS handles in the
|
|
|
|
|
/// in_pProcesses array does not identify a valid process.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferCreateFromMemory(
|
|
|
|
|
uint64_t in_Size,
|
2017-04-10 11:32:00 +00:00
|
|
|
|
COI_BUFFER_TYPE in_Type,
|
2015-08-28 15:33:40 +00:00
|
|
|
|
uint32_t in_Flags,
|
|
|
|
|
void* in_Memory,
|
|
|
|
|
uint32_t in_NumProcesses,
|
|
|
|
|
const COIPROCESS* in_pProcesses,
|
|
|
|
|
COIBUFFER* out_pBuffer);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Destroys a buffer. Will block on completion of any operations on the
|
|
|
|
|
/// buffer, such as COIPipelineRunFunction or COIBufferCopy. Will block until
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// all COIBufferAddRef calls have had a matching COIBufferReleaseRef call
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// made. will not block on an outstanding COIBufferUnmap but will instead
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// return COI_RETRY.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] Handle of the buffer to destroy.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was destroyed.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if the buffer is currently mapped. The buffer must
|
|
|
|
|
/// first be unmapped before it can be destroyed.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if the sub-buffers created from this buffer are not yet
|
|
|
|
|
/// destroyed
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferDestroy(
|
|
|
|
|
COIBUFFER in_Buffer);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// This call initiates a request to access a region of a buffer. Multiple
|
|
|
|
|
/// overlapping (or non overlapping) regions can be mapped simultaneously for
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// any given buffer. If a completion event is specified this call will
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// queue a request for the data which will be satisfied when the buffer is
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// available. Once all conditions are met the completion event will be
|
|
|
|
|
/// signaled and the user can access the data at out_ppData. The user can call
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// COIEventWait with out_pCompletion to find out when the map operation has
|
|
|
|
|
/// completed. If the user accesses the data before the map operation is
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// complete the results are undefined. If out_pCompletion is NULL then this
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// call blocks until the map operation completes and when this call returns
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// out_ppData can be safely accessed. This call returns a map instance handle
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// in an out parameter which must be passed into COIBufferUnmap when the user
|
|
|
|
|
/// no longer needs access to that region of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// The address returned from COIBufferMap may point to memory that
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// manages on behalf of the user. The user must not free or reallocate this
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// memory, Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// will perform any necessary cleanup when the buffer is
|
|
|
|
|
/// destroyed.
|
|
|
|
|
///
|
|
|
|
|
/// Note that different types of buffers behave differently when mapped.
|
|
|
|
|
/// For instance, mapping a COI_BUFFER_NORMAL for write must stall if the
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// buffer is currently being written to by a run function. Mapping
|
|
|
|
|
/// a COI_BUFFER_PINNED buffer will not affect other functions that use
|
|
|
|
|
/// that buffer since a COI_BUFFER_PINNED buffer can be mapped at any time.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// The asynchronous operation of COIBufferMap will likely be most useful when
|
|
|
|
|
/// paired with a COI_BUFFER_NORMAL.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] Handle for the buffer to map.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Offset into the buffer that a pointer should be returned
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// for. The value 0 can be passed in to signify that the mapped
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// region should start at the beginning of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] Length of the buffer area to map. This parameter, in
|
|
|
|
|
/// combination with in_Offset, allows the caller to specify
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// that only a subset of an entire buffer need be mapped. A
|
|
|
|
|
/// value of 0 can be passed in only if in_Offset is 0, to signify
|
|
|
|
|
/// that the mapped region is the entire buffer.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The access type that is needed by the application. This will
|
|
|
|
|
/// affect how the data can be accessed once the map operation
|
|
|
|
|
/// completes. See the COI_MAP_TYPE enum for more details.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the map
|
|
|
|
|
/// call initiation to wait for any events to be signaled before
|
|
|
|
|
/// starting the map operations.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this map operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between asynchronous
|
|
|
|
|
/// map calls and other operations such as run functions or other
|
|
|
|
|
/// asynchronous map calls. The user may pass in NULL if they do not
|
|
|
|
|
/// wish to wait for any dependencies to complete before initiating map
|
|
|
|
|
/// operations.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional pointer to a COIEVENT object
|
|
|
|
|
/// that will be signaled when a map call with the passed in buffer
|
|
|
|
|
/// would complete immediately, that is, the buffer memory has been
|
|
|
|
|
/// allocated on the source and its contents updated. The user may pass
|
|
|
|
|
/// in NULL if the user wants COIBufferMap to perform a blocking map
|
|
|
|
|
/// operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pMapInstance
|
|
|
|
|
/// [out] A pointer to a COIMAPINSTANCE which represents this mapping
|
|
|
|
|
/// of the buffer and must be passed in to COIBufferUnmap when access
|
|
|
|
|
/// to this region of the buffer data is no longer needed.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_ppData
|
|
|
|
|
/// [out] Pointer to the buffer data. The data will only be valid
|
|
|
|
|
/// when the completion object is signaled, or for a synchronous
|
|
|
|
|
/// map operation with the call to map returns.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the map request succeeds.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset of (in_Offset + in_Length) exceeds
|
|
|
|
|
/// the size of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Length is 0, but in_Offset is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Type is not a valid COI_MAP_TYPE.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_NumDependencies is non-zero while
|
|
|
|
|
/// in_pDependencies was passed in as NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is non-NULL but
|
|
|
|
|
/// in_NumDependencies is zero.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_Type of map is not a valid type
|
|
|
|
|
/// for in_Buffer's type of buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if out_pMapInstance or out_ppData is NULL.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferMap(
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_MAP_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion,
|
|
|
|
|
COIMAPINSTANCE* out_pMapInstance,
|
|
|
|
|
void** out_ppData);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Disables Source access to the region of the buffer that was provided
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// through the corresponding call to COIBufferMap. The number of calls to
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// COIBufferUnmap() should always match the number of calls made to
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// COIBufferMap(). The data pointer returned from the COIBufferMap() call
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// will be invalid after this call.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_MapInstance
|
|
|
|
|
/// [in] buffer map instance handle to unmap.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the unmap call to
|
|
|
|
|
/// wait for any events to be signaled before performing the unmap
|
|
|
|
|
/// operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this unmap operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between asynchronous
|
|
|
|
|
/// unmap calls and other operations such as run functions or other
|
|
|
|
|
/// asynchronous unmap calls. The user may pass in NULL if they do not
|
|
|
|
|
/// wish to wait for any dependencies to complete before initiating
|
|
|
|
|
/// unmap operations.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional pointer to a COIEVENT object that will be
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// signaled when the unmap is complete. The user may pass in NULL if
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// the user wants COIBufferUnmap to perform a blocking unmap
|
|
|
|
|
/// operation.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS upon successful unmapping of the buffer instance.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the passed in map instance handle was NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferUnmap(
|
|
|
|
|
COIMAPINSTANCE in_MapInstance,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Gets the Sink's virtual address of the buffer for the first process
|
|
|
|
|
/// that is using the buffer. This is the same address
|
|
|
|
|
/// that is passed to the run function on the Sink. The virtual
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// address assigned to the buffer for use on the sink is fixed;
|
|
|
|
|
/// the buffer will always be present at that virtual address on the sink
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// and will not get a different virtual address across different
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// RunFunctions.
|
|
|
|
|
/// This address is only valid on the Sink and should not be dereferenced on
|
|
|
|
|
/// the Source (except for the special case of buffers created with the
|
|
|
|
|
/// COI_SAME_ADDRESS flag).
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] Buffer handle
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pAddress
|
|
|
|
|
/// [out] pointer to a uint64_t* that will be filled with the address.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS upon successful return of the buffer's address.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the passed in buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the out_pAddress parameter was invalid.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferGetSinkAddress(
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t* out_pAddress);
|
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Gets the Sink's virtual address of the buffer. This is the same
|
|
|
|
|
/// address that is passed to the run function on the Sink. The virtual
|
|
|
|
|
/// address assigned to the buffer for use on the sink is fixed;
|
|
|
|
|
/// the buffer will always be present at that virtual address on the sink
|
|
|
|
|
/// and will not get a different virtual address across different
|
|
|
|
|
/// RunFunctions.
|
|
|
|
|
/// This address is only valid on the Sink and should not be dereferenced on
|
|
|
|
|
/// the Source (except for the special case of buffers created with the
|
|
|
|
|
/// COI_SAME_ADDRESS flag).
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Process
|
|
|
|
|
/// [in] The process for which the address should be returned.
|
|
|
|
|
/// Special handle value 0 can be passed to the function;
|
|
|
|
|
/// in this case, address for the first valid process will be returned
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] Buffer handle
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pAddress
|
|
|
|
|
/// [out] pointer to a uint64_t* that will be filled with the address.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS upon successful return of the buffer's address.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the passed in buffer or process
|
|
|
|
|
/// handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the out_pAddress parameter was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if the in_Process is not valid for in_Buffer at the
|
|
|
|
|
/// moment of calling the function.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferGetSinkAddressEx(
|
|
|
|
|
COIPROCESS in_Process,
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t* out_pAddress);
|
|
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data from a normal virtual address into an existing COIBUFFER.
|
|
|
|
|
/// Please note that COIBufferWrite does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferWrite will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_DestBuffer
|
|
|
|
|
/// [in] Buffer to write into.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestProcess
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// [in] A pointer to the process to which the data will be written.
|
|
|
|
|
/// Buffer is updated only in this process and invalidated in other
|
|
|
|
|
/// processes. Only a single process can be specified.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// Can be left NULL and default behavior will be chosen, which
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// chooses the first valid process in which regions are found. Other
|
|
|
|
|
/// buffer regions are invalidated if not updated.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Location in the buffer to start writing to.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pSourceData
|
|
|
|
|
/// [in] A pointer to local memory that should be copied into the
|
|
|
|
|
/// provided buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The number of bytes to write from in_pSourceData into
|
|
|
|
|
/// in_DestBuffer. Must not be larger than the size of in_DestBuffer
|
|
|
|
|
/// and must not over run in_DestBuffer if an in_Offset is provided.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the write call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// write operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this write operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer write
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the write.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the write has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the write with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the write is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @return COI_SUCCESS if the buffer was written successfully.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the in_pSourceData pointer is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of
|
|
|
|
|
/// the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Length is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_DestBuffer is mapped and is not a COI_BUFFER_PINNED
|
|
|
|
|
/// buffer or COI_BUFFER_OPENCL buffer.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
2017-04-10 11:32:00 +00:00
|
|
|
|
COIBufferWriteEx(
|
2015-08-28 15:33:40 +00:00
|
|
|
|
COIBUFFER in_DestBuffer,
|
|
|
|
|
const COIPROCESS in_DestProcess,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
const void* in_pSourceData,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
2017-04-10 11:32:00 +00:00
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data specified by multi-dimensional array data structure into another
|
|
|
|
|
/// multi-dimensional array in an existing COIBUFFER.
|
|
|
|
|
/// Arrays with more than 3 dimensions are not supported.
|
|
|
|
|
/// Different numbers of elements between src and destination is not supported.
|
|
|
|
|
/// Please note that COIBufferWriteMultiD does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferWriteMultiD will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestBuffer
|
|
|
|
|
/// [in] Buffer to write into.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestProcess
|
|
|
|
|
/// [in] A pointer to the process to which the data will be written.
|
|
|
|
|
/// Buffer is updated only in this process and invalidated in other
|
|
|
|
|
/// processes. Only a single process can be specified.
|
|
|
|
|
/// Can be left NULL and default behavior will be chosen, which
|
|
|
|
|
/// chooses the first valid process in which regions are found. Other
|
|
|
|
|
/// buffer regions are invalidated if not updated.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Start location of the destination array within the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestArray
|
|
|
|
|
/// [in] A pointer to a data structure describing the structure of
|
|
|
|
|
/// the data array in the buffer. Total size must not be larger than
|
|
|
|
|
/// the size of in_DestBuffer. The base field of this structure will
|
|
|
|
|
/// be ignored.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SrcArray
|
|
|
|
|
/// [in] A pointer to a data structure describing the structure of
|
|
|
|
|
/// the data array in local memory that should be copied. in_SrcArray
|
|
|
|
|
/// and in_DestArry must have the same number of elements. The base
|
|
|
|
|
/// field of this structure should be the virtual pointer to the local
|
|
|
|
|
/// memory in which this array is located.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the write call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// write operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this write operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer write
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the write.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the write has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the write with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the write is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was copied successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer or process handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED or dimension of destination or source arrays
|
|
|
|
|
/// are greater than 3 or less than 1
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the pointer in_SrcArray->base is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset + size of in_DestArray exceeds the
|
|
|
|
|
/// size of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_MEMORY if any allocation of memory fails
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_DestBuffer is mapped and is not a COI_BUFFER_PINNED
|
|
|
|
|
/// buffer or COI_BUFFER_OPENCL buffer.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferWriteMultiD(
|
|
|
|
|
COIBUFFER in_DestBuffer,
|
|
|
|
|
const COIPROCESS in_DestProcess,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
struct arr_desc* in_DestArray,
|
|
|
|
|
struct arr_desc* in_SrcArray,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data specified by multi-dimensional array data structure from an
|
|
|
|
|
/// existing COIBUFFER to another multi-dimensional array located in memory.
|
|
|
|
|
/// Arrays with more than 3 dimensions are not supported.
|
|
|
|
|
/// Different numbers of elements between source and destination are not supported.
|
|
|
|
|
/// Please note that COIBufferReadMultiD does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferReadMultiD will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceBuffer
|
|
|
|
|
/// [in] Buffer to read from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Start location of the source array within the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestArray
|
|
|
|
|
/// [in] A pointer to a data structure describing the structure of
|
|
|
|
|
/// the data array in the buffer. Total size must not be larger than
|
|
|
|
|
/// the size of in_DestBuffer. The base field of this structure will
|
|
|
|
|
/// be ignored.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SrcArray
|
|
|
|
|
/// [in] A pointer to a data structure describing the structure of
|
|
|
|
|
/// the data array in local memory that should be copied. in_SrcArray
|
|
|
|
|
/// and in_DestArry must have the same number of elements. The base
|
|
|
|
|
/// field of this structure should be the virtual pointer to the local
|
|
|
|
|
/// memory in which this array is located.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the write call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// write operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this write operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer write
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the write.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the write has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the write with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the write is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was written successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer or process handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED or dimension of destination or source arrays
|
|
|
|
|
/// are greater than 3 or less than 1
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the pointer in_DestArray->base is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset + size of in_SourceArray exceeds the
|
|
|
|
|
/// size of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_MEMORY if any allocation of memory fails
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_SourceBuffer is mapped and is not a COI_BUFFER_PINNED
|
|
|
|
|
/// buffer or COI_BUFFER_OPENCL buffer.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferReadMultiD(
|
|
|
|
|
COIBUFFER in_SourceBuffer,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
struct arr_desc* in_DestArray,
|
|
|
|
|
struct arr_desc* in_SrcArray,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data from a normal virtual address into an existing COIBUFFER.
|
|
|
|
|
/// Please note that COIBufferWrite does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferWrite will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestBuffer
|
|
|
|
|
/// [in] Buffer to write into.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Location in the buffer to start writing to.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pSourceData
|
|
|
|
|
/// [in] A pointer to local memory that should be copied into the
|
|
|
|
|
/// provided buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The number of bytes to write from in_pSourceData into
|
|
|
|
|
/// in_DestBuffer. Must not be larger than the size of in_DestBuffer
|
|
|
|
|
/// and must not over run in_DestBuffer if an in_Offset is provided.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the write call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// write operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this write operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer write
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the write.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the write has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the write with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the write is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was copied successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the in_pSourceData pointer is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of
|
|
|
|
|
/// the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Length is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_DestBuffer is mapped and is not a COI_BUFFER_PINNED
|
|
|
|
|
/// buffer or COI_BUFFER_OPENCL buffer.
|
|
|
|
|
///
|
2015-08-28 15:33:40 +00:00
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferWrite(
|
|
|
|
|
COIBUFFER in_DestBuffer,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
const void* in_pSourceData,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data from a buffer into local memory.
|
|
|
|
|
/// Please note that COIBufferRead does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferRead will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceBuffer
|
|
|
|
|
/// [in] Buffer to read from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Location in the buffer to start reading from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDestData
|
|
|
|
|
/// [in] A pointer to local memory that should be written into from
|
|
|
|
|
/// the provided buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The number of bytes to write from in_SourceBuffer into
|
|
|
|
|
/// in_pDestData. Must not be larger than the size of in_SourceBuffer
|
|
|
|
|
/// and must not over run in_SourceBuffer if an in_Offset is provided.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the read call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// read operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this read operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer read
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the read.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the read has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the read with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the read is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was copied successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if the buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset is beyond the end of the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Offset + in_Length exceeds the size of
|
|
|
|
|
/// the buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Length is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the in_pDestData pointer is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_SourceBuffer is mapped and is not a
|
|
|
|
|
/// COI_BUFFER_PINNED buffer or COI_BUFFER_OPENCL buffer.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferRead(
|
|
|
|
|
COIBUFFER in_SourceBuffer,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
void* in_pDestData,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data between two buffers. It also allows copying within the same
|
|
|
|
|
/// buffer. For copy within the same buffer, if source and destination regions
|
|
|
|
|
/// overlap then this API returns error.
|
|
|
|
|
/// Please note that COIBufferCopy does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferCopy will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_DestBuffer
|
|
|
|
|
/// [in] Buffer to copy into.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
///
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// @param in_DestProcess
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// [in] A pointer to the process to which the data will be written.
|
|
|
|
|
/// Buffer is updated only in this process and invalidated in other
|
|
|
|
|
/// processes. Only a single process can be specified.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// Can be left NULL and default behavior will be chosen, which
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// chooses the first valid process in which regions are found. Other
|
|
|
|
|
/// buffer regions are invalidated if not updated.
|
2015-08-28 15:33:40 +00:00
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceBuffer
|
|
|
|
|
/// [in] Buffer to copy from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestOffset
|
|
|
|
|
/// [in] Location in the destination buffer to start writing to.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceOffset
|
|
|
|
|
/// [in] Location in the source buffer to start reading from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The number of bytes to copy from in_SourceBuffer into
|
|
|
|
|
/// in_DestinationBuffer.
|
|
|
|
|
/// If the length is specified as zero then length to be copied
|
|
|
|
|
// is entire destination buffer's length.
|
|
|
|
|
/// Must not be larger than the size of in_SourceBuffer or
|
|
|
|
|
/// in_DestBuffer and must not over run in_SourceBuffer or
|
|
|
|
|
/// in_DestBuffer if offsets are specified.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the copy call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// copy operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this copy operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer copy
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the copy.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the copy has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the copy with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the copy is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was copied successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if either buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_MEMORY_OVERLAP if in_SourceBuffer and in_DestBuffer are the
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// same buffer(or have the same parent buffer) and the source and
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// destination regions overlap
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_DestOffset is is beyond the end of
|
|
|
|
|
/// in_DestBuffer
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_SourceOffset is beyond the end of
|
|
|
|
|
/// in_SourceBuffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_DestOffset + in_Length exceeds the size of
|
|
|
|
|
/// the in_DestBuffer
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_SourceOffset + in_Length exceeds
|
|
|
|
|
/// the size of in_SourceBuffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_DestBuffer or in_SourceBuffer are mapped and not
|
|
|
|
|
/// COI_BUFFER_PINNED buffers or COI_BUFFER_OPENCL buffers.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
2017-04-10 11:32:00 +00:00
|
|
|
|
COIBufferCopyEx(
|
2015-08-28 15:33:40 +00:00
|
|
|
|
COIBUFFER in_DestBuffer,
|
|
|
|
|
const COIPROCESS in_DestProcess,
|
|
|
|
|
COIBUFFER in_SourceBuffer,
|
|
|
|
|
uint64_t in_DestOffset,
|
|
|
|
|
uint64_t in_SourceOffset,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
2017-04-10 11:32:00 +00:00
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Copy data between two buffers. It also allows copying within the same
|
|
|
|
|
/// buffer. For copy within the same buffer, if source and destination regions
|
|
|
|
|
/// overlap then this API returns error.
|
|
|
|
|
/// Please note that COIBufferCopy does not follow implicit buffer
|
|
|
|
|
/// dependencies. If a buffer is in use in a run function or has been added
|
|
|
|
|
/// to a process using COIBufferAddRef the call to COIBufferCopy will not
|
|
|
|
|
/// wait, it will still copy data immediately.
|
|
|
|
|
/// This is to facilitate a usage model where a buffer is being used outside
|
|
|
|
|
/// of a run function, for example in a spawned thread, but data still needs
|
|
|
|
|
/// to be transferred to or from the buffer.
|
|
|
|
|
/// Additionally this means that if more than one DMA channel is enabled,
|
|
|
|
|
/// (See COIProcessConfigureDMA) operations to the same buffer may
|
|
|
|
|
/// happen in parallel if they can be assigned to different DMA hardware.
|
|
|
|
|
/// So it is highly recommended to use explicit event dependencies to
|
|
|
|
|
/// order operations where needed.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestBuffer
|
|
|
|
|
/// [in] Buffer to copy into.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceBuffer
|
|
|
|
|
/// [in] Buffer to copy from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DestOffset
|
|
|
|
|
/// [in] Location in the destination buffer to start writing to.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_SourceOffset
|
|
|
|
|
/// [in] Location in the source buffer to start reading from.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The number of bytes to copy from in_SourceBuffer into
|
|
|
|
|
/// in_DestinationBuffer.
|
|
|
|
|
/// If the length is specified as zero then length to be copied
|
|
|
|
|
/// is entire destination buffer's length.
|
|
|
|
|
/// Must not be larger than the size of in_SourceBuffer or
|
|
|
|
|
/// in_DestBuffer and must not over run in_SourceBuffer or
|
|
|
|
|
/// in_DestBuffer if offsets are specified.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Type
|
|
|
|
|
/// [in] The type of copy operation to use, one of either
|
|
|
|
|
/// COI_COPY_UNSPECIFIED, COI_COPY_USE_DMA, COI_COPY_USE_CPU.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the copy call to
|
|
|
|
|
/// wait for any additional events to be signaled before starting the
|
|
|
|
|
/// copy operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this copy operation will wait for before starting.
|
|
|
|
|
/// This allows the user to create dependencies between buffer copy
|
|
|
|
|
/// calls and other operations such as run functions and map calls. The
|
|
|
|
|
/// user may pass in NULL if they do not wish to wait for any
|
|
|
|
|
/// additional dependencies to complete before doing the copy.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the copy has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the copy with regard to future operations.
|
|
|
|
|
/// If no completion event is passed in then the copy is
|
|
|
|
|
/// synchronous and will block until the transfer is complete.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer was copied successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if either buffer handle was invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_MEMORY_OVERLAP if in_SourceBuffer and in_DestBuffer are the
|
|
|
|
|
/// same buffer(or have the same parent buffer) and the source and
|
|
|
|
|
/// destination regions overlap
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_DestOffset is is beyond the end of
|
|
|
|
|
/// in_DestBuffer
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_SourceOffset is beyond the end of
|
|
|
|
|
/// in_SourceBuffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_DestOffset + in_Length exceeds the size of
|
|
|
|
|
/// the in_DestBuffer
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_SourceOffset + in_Length exceeds
|
|
|
|
|
/// the size of in_SourceBuffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_pDependencies is non NULL but
|
|
|
|
|
/// in_NumDependencies is 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if in_pDependencies is NULL but
|
|
|
|
|
/// in_NumDependencies is not 0.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_RETRY if in_DestBuffer or in_SourceBuffer are mapped and not
|
|
|
|
|
/// COI_BUFFER_PINNED buffers or COI_BUFFER_OPENCL buffers.
|
|
|
|
|
///
|
2015-08-28 15:33:40 +00:00
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferCopy(
|
|
|
|
|
COIBUFFER in_DestBuffer,
|
|
|
|
|
COIBUFFER in_SourceBuffer,
|
|
|
|
|
uint64_t in_DestOffset,
|
|
|
|
|
uint64_t in_SourceOffset,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
COI_COPY_TYPE in_Type,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
2017-04-10 11:32:00 +00:00
|
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// This API allows an experienced Intel(R) Coprocessor Offload Infrastructure
|
|
|
|
|
/// (Intel(R) COI) developer to set where a COIBUFFER is
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// located and when the COIBUFFER's data is moved. This functionality is
|
|
|
|
|
/// useful when the developer knows when and where a buffer is going to be
|
|
|
|
|
/// accessed. It allows the data movement to happen sooner than if the
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// runtime tried to manage the buffer placement itself. The advantage of
|
|
|
|
|
/// this API is that the developer knows much more about their own
|
|
|
|
|
/// application's data access patterns and can therefore optimize the data
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// access to be much more efficient than the Intel(R)Coprocessor Offload
|
|
|
|
|
/// Infrastructure (Intel(R) COI) runtime. Using this API may yield better
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// memory utilization, lower latency and overall improved workload
|
|
|
|
|
/// throughput.
|
|
|
|
|
/// This API does respect implicit dependencies for buffer read/write hazards.
|
|
|
|
|
/// For example, if the buffer is being written in one COIPROCESS and the user
|
|
|
|
|
/// requests the buffer be placed in another COIPROCESS then this API will wait
|
|
|
|
|
/// for the first access to complete before moving the buffer.
|
|
|
|
|
/// This API is not required for program correctness. It is intended solely
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// for advanced Intel(R) Coprocessor Offload Infrastructure (Intel(R) COI)
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// developers who wish to fine tune their application performance
|
|
|
|
|
/// Cases where "a change in state" is an error condition the change just gets
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// ignored without any error. This is because the SetState can be a
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// nonblocking call and in such cases we can't rely on the state of the buffer
|
|
|
|
|
/// at the time of the call. We can do the transition checks only at the time
|
|
|
|
|
/// when the actual state change happens (which is something in future).
|
|
|
|
|
/// Currently there is no way to report an error from something that happens in
|
|
|
|
|
/// future and that is why such state transitions are nop. One example is using
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// VALID_MAY_DROP with COI_SINK_OWNERS when buffer is not valid at source.
|
|
|
|
|
/// This operation will be a nop if at the time of actual state change the
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// buffer is not valid at source.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] The buffer to modify.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Process
|
|
|
|
|
/// [in] The process where the state is being modified for this
|
|
|
|
|
/// buffer. To modify buffer's state on source process use
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// COI_PROCESS_SOURCE as process handle. To modify buffer's
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// state on all processes where buffer is valid use COI_SINK_OWNERS
|
|
|
|
|
/// as the process handle.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_State
|
|
|
|
|
/// [in] The new state for the buffer. The buffer's state could be
|
|
|
|
|
/// set to invalid on one of the sink processes where it is being
|
|
|
|
|
/// used.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_DataMove
|
|
|
|
|
/// [in] A flag to indicate if the buffer's data should be moved
|
|
|
|
|
/// when the state is changed. For instance, a buffer's state may
|
|
|
|
|
/// be set to valid on a process and the data move flag may be set to
|
|
|
|
|
/// COI_BUFFER_MOVE which would cause the buffer contents to be
|
|
|
|
|
/// copied to the process where it is now valid.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_NumDependencies
|
|
|
|
|
/// [in] The number of dependencies specified in the in_pDependencies
|
|
|
|
|
/// array. This may be 0 if the caller does not want the SetState call
|
|
|
|
|
/// to wait for any additional events to be signaled before starting
|
|
|
|
|
/// this operation.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_pDependencies
|
|
|
|
|
/// [in] An optional array of handles to previously created COIEVENT
|
|
|
|
|
/// objects that this SetState operation will wait for before starting
|
|
|
|
|
/// This allows the user to create dependencies between buffer
|
|
|
|
|
/// SetState calls and other operations such as run functions and map
|
|
|
|
|
/// calls. The user may pass in NULL if they do not wish to wait for
|
|
|
|
|
/// any additional dependencies to complete before doing the SetState
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pCompletion
|
|
|
|
|
/// [out] An optional event to be signaled when the SetState has
|
|
|
|
|
/// completed. This event can be used as a dependency to order
|
|
|
|
|
/// the SetState with regard to future operations.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// If no completion event is passed in then the state changing is
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// synchronous and will block until the SetState and dma transfers
|
|
|
|
|
/// related to this operation are complete.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the buffer's state was changed successfully.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if in_Buffer or in_Process is invalid.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than
|
|
|
|
|
/// COI_BUFFER_NORMAL or COI_BUFFER_OPENCL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_State is COI_BUFFER_VALID_MAY_DROP
|
|
|
|
|
/// and the in_Process is COI_PROCESS_SOURCE.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_ARGUMENT_MISMATCH if the in_Process is COI_SINK_OWNERS and the
|
|
|
|
|
/// COI_BUFFER_MOVE is passed as move flag.
|
|
|
|
|
///
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// @return COI_MISSING_DEPENDENCY if buffer was not created on the process
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// handle that was passed in.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferSetState(
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
COIPROCESS in_Process,
|
|
|
|
|
COI_BUFFER_STATE in_State,
|
|
|
|
|
COI_BUFFER_MOVE_FLAG in_DataMove,
|
|
|
|
|
uint32_t in_NumDependencies,
|
|
|
|
|
const COIEVENT* in_pDependencies,
|
|
|
|
|
COIEVENT* out_pCompletion);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Creates a sub-buffer that is a reference to a portion of an existing
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// buffer. The returned buffer handle can be used in all API calls that the
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// original buffer handle could be used in except COIBufferCreateSubBuffer.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
/// Sub buffers out of Huge Page Buffer are also supported but the original
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// buffer needs to be a OPENCL buffer created with COI_OPTIMIZE_HUGE_PAGE_SIZE
|
|
|
|
|
/// flag.
|
|
|
|
|
///
|
|
|
|
|
/// When the sub-buffer is used only the corresponding sub-section of the
|
|
|
|
|
/// original buffer is used or affected.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] The original buffer that this new sub-buffer is a reference
|
|
|
|
|
/// to.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Length
|
|
|
|
|
/// [in] The length of the sub-buffer in number of bytes.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Offset
|
|
|
|
|
/// [in] Where in the original buffer to start this sub-buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @param out_pSubBuffer
|
|
|
|
|
/// [out] Pointer to a buffer handle that is filled in with the newly
|
|
|
|
|
/// created sub-buffer.
|
2017-04-10 11:32:00 +00:00
|
|
|
|
///
|
2015-08-28 15:33:40 +00:00
|
|
|
|
/// @return COI_SUCCESS if the sub-buffer was created
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if in_Buffer is not a valid buffer handle.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if in_Length is zero, or if in_Offset + in_Length
|
|
|
|
|
/// is greater than the size of the original buffer.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_MEMORY if allocating the buffer fails.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_POINTER if the out_pSubBuffer pointer is NULL.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_SUPPORTED if the in_Buffer is of any type other than
|
|
|
|
|
/// COI_BUFFER_OPENCL
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferCreateSubBuffer(
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t in_Length,
|
|
|
|
|
uint64_t in_Offset,
|
|
|
|
|
COIBUFFER* out_pSubBuffer);
|
|
|
|
|
|
2017-04-10 11:32:00 +00:00
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Releases the reference count on the specified buffer and process by
|
|
|
|
|
/// in_ReleaseRefcnt. The returned result being COI_SUCCESS indicates that the
|
|
|
|
|
/// specified process contains a reference to the specified buffer that has a
|
|
|
|
|
/// refcnt that can be decremented. Otherwise, if the buffer or process
|
|
|
|
|
/// specified do not exist, then COI_INVALID_HANDLE will be returned. If the
|
|
|
|
|
/// process does not contain a reference to the specified buffer then
|
|
|
|
|
/// COI_OUT_OF_RANGE will be returned.
|
|
|
|
|
///
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Process
|
|
|
|
|
/// [in] The COI Process whose reference count for the specified buffer
|
|
|
|
|
/// the user wants to decrement.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] The buffer used in the specified coi process in which the user
|
|
|
|
|
/// wants to decrement the reference count.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_ReleaseRefcnt
|
|
|
|
|
/// [in] The value the reference count will be decremented by.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the reference count was successfully decremented.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if in_Buffer or in_Process are invalid handles.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_OUT_OF_RANGE if the reference for the specified buffer or
|
|
|
|
|
/// process does not exist.
|
|
|
|
|
///
|
|
|
|
|
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferReleaseRefcnt(
|
|
|
|
|
COIPROCESS in_Process,
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t in_ReleaseRefcnt);
|
|
|
|
|
|
|
|
|
|
//////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
///
|
|
|
|
|
/// Increments the reference count on the specified buffer and process by
|
|
|
|
|
/// in_AddRefcnt. The returned result being COI_SUCCESS indicates that the
|
|
|
|
|
/// specified process contains a reference to the specified buffer or a new
|
|
|
|
|
/// reference has been created and that reference has a new refcnt. Otherwise,
|
|
|
|
|
/// if the buffer or process specified do not exist, then COI_INVALID_HANDLE
|
|
|
|
|
/// will be returned. If the input buffer is not valid on the target process
|
|
|
|
|
/// then COI_NOT_INITIALIZED will be returned since the buffer is not current
|
|
|
|
|
/// or allocated on the process.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Process
|
|
|
|
|
/// [in] The COI Process whose reference count for the specified buffer
|
|
|
|
|
/// the user wants to increment.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_Buffer
|
|
|
|
|
/// [in] The buffer used in the specified coi process in which the user
|
|
|
|
|
/// wants to increment the reference count.
|
|
|
|
|
///
|
|
|
|
|
/// @param in_AddRefcnt
|
|
|
|
|
/// [in] The value the reference count will be incremented by.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_SUCCESS if the reference count was successfully incremented.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_INVALID_HANDLE if in_Buffer or in_Process are invalid handles.
|
|
|
|
|
///
|
|
|
|
|
/// @return COI_NOT_INITIALIZED if in_Buffer does not have a buffer state of
|
|
|
|
|
/// COI_BUFFER_VALID on the in_Process.
|
|
|
|
|
///
|
|
|
|
|
COIACCESSAPI
|
|
|
|
|
COIRESULT
|
|
|
|
|
COIBufferAddRefcnt(
|
|
|
|
|
COIPROCESS in_Process,
|
|
|
|
|
COIBUFFER in_Buffer,
|
|
|
|
|
uint64_t in_AddRefcnt);
|
|
|
|
|
|
2015-08-28 15:33:40 +00:00
|
|
|
|
#ifdef __cplusplus
|
|
|
|
|
} /* extern "C" */
|
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
#endif /* _COIBUFFER_SOURCE_H */
|
|
|
|
|
|
|
|
|
|
/*! @} */
|