diff options
Diffstat (limited to 'liboffloadmic/include/coi/sink/COIBuffer_sink.h')
| -rw-r--r-- | liboffloadmic/include/coi/sink/COIBuffer_sink.h | 53 |
1 files changed, 28 insertions, 25 deletions
diff --git a/liboffloadmic/include/coi/sink/COIBuffer_sink.h b/liboffloadmic/include/coi/sink/COIBuffer_sink.h index 66d0549010d8..2e51e92f920a 100644 --- a/liboffloadmic/include/coi/sink/COIBuffer_sink.h +++ b/liboffloadmic/include/coi/sink/COIBuffer_sink.h @@ -1,5 +1,5 @@ /* - * Copyright 2010-2013 Intel Corporation. + * Copyright 2010-2015 Intel Corporation. * * 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 @@ -45,7 +45,7 @@ * @addtogroup COIBufferSink @{ -* @file sink\COIBuffer_sink.h +* @file sink\COIBuffer_sink.h */ #ifndef DOXYGEN_SHOULD_SKIP_THIS #include "../common/COITypes_common.h" @@ -54,29 +54,29 @@ #ifdef __cplusplus extern "C" { -#endif +#endif ////////////////////////////////////////////////////////////////////////////// /// -/// Adds a reference to the memory of a buffer. The memory of the buffer -/// will remain on the device until both a corresponding COIBufferReleaseRef() +/// Adds a reference to the memory of a buffer. The memory of the buffer +/// will remain on the device until both a corresponding COIBufferReleaseRef() /// call is made and the run function that delivered the buffer returns. /// -/// Intel® Coprocessor Offload Infrastructure (Intel® COI) streaming buffers should not be AddRef'd. Doing so may result in -/// unpredictable results or may cause the sink process to crash. +/// Running this API in a thread spawned within the run function is not +/// supported and will cause unpredictable results and may cause data corruption. /// -/// @warning 1.It is possible for enqueued run functions to be unable to -/// execute due to all card memory being occupied by addref'ed +/// @warning 1.It is possible for enqueued run functions to be unable to +/// execute due to all card memory being occupied by AddRef'd /// buffers. As such, it is important that whenever a buffer is -/// addref'd that there be no dependencies on future run functions +/// AddRef'd that there be no dependencies on future run functions /// for progress to be made towards releasing the buffer. -/// 2.It is important that AddRef is called within the scope of -/// run function that carries the buffer to be addref'ed. +/// 2.It is important that AddRef is called within the scope of +/// run function that carries the buffer to be AddRef'd. /// /// @param in_pBuffer -/// [in] Pointer to the start of a buffer being addref'ed, that was +/// [in] Pointer to the start of a buffer being AddRef'd, that was /// passed in at the start of the run function. -/// +/// /// @return COI_SUCCESS if the buffer ref count was successfully incremented. /// /// @return COI_INVALID_POINTER if the buffer pointer is NULL. @@ -90,30 +90,33 @@ COIBufferAddRef( ////////////////////////////////////////////////////////////////////////////// /// -/// Removes a reference to the memory of a buffer. The memory of the buffer +/// Removes a reference to the memory of a buffer. The memory of the buffer /// will be eligible for being freed on the device when the following /// conditions are met: the run function that delivered the buffer -/// returns, and the number of calls to COIBufferReleaseRef() matches the +/// returns, and the number of calls to COIBufferReleaseRef() matches the /// number of calls to COIBufferAddRef(). +// +/// Running this API in a thread spawned within the run function is not +/// supported and will cause unpredictable results and may cause data corruption. /// -/// @warning When a buffer is addref'ed it is assumed that it is in use and all +/// @warning When a buffer is AddRef'd it is assumed that it is in use and all /// other operations on that buffer waits for ReleaseRef() to happen. -/// So you cannot pass the addref'ed buffer's handle to RunFunction -/// that calls ReleaseRef(). This is a circular dependency and will -/// cause a deadlock. Buffer's pointer (buffer's sink side +/// So you cannot pass the AddRef'd buffer's handle to RunFunction +/// that calls ReleaseRef(). This is a circular dependency and will +/// cause a deadlock. Buffer's pointer (buffer's sink side /// address/pointer which is different than source side BUFFER handle) -/// needs to be stored somewhere to retrieve it later to use in +/// needs to be stored somewhere to retrieve it later to use in /// ReleaseRef. /// /// @param in_pBuffer -/// [in] Pointer to the start of a buffer previously addref'ed, that +/// [in] Pointer to the start of a buffer previously AddRef'd, that /// was passed in at the start of the run function. -/// +/// /// @return COI_SUCCESS if the buffer refcount was successfully decremented. /// /// @return COI_INVALID_POINTER if the buffer pointer was invalid. /// -/// @return COI_INVALID_HANDLE if the buffer did not have COIBufferAddRef() +/// @return COI_INVALID_HANDLE if the buffer did not have COIBufferAddRef() /// previously called on it. /// COIRESULT @@ -123,7 +126,7 @@ COIBufferReleaseRef( #ifdef __cplusplus } /* extern "C" */ -#endif +#endif #endif /* _COIBUFFER_SINK_H */ |