1 /* 2 * Copyright 2010-2016 Intel Corporation. 3 * 4 * This library is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU Lesser General Public License as published 6 * by the Free Software Foundation, version 2.1. 7 * 8 * This library is distributed in the hope that it will be useful, 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 * Lesser General Public License for more details. 12 * 13 * You should have received a copy of the GNU Lesser General Public 14 * License along with this library; if not, write to the Free Software 15 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 16 * 02110-1301 USA. 17 * 18 * Disclaimer: The codes contained in these modules may be specific 19 * to the Intel Software Development Platform codenamed Knights Ferry, 20 * and the Intel product codenamed Knights Corner, and are not backward 21 * compatible with other Intel products. Additionally, Intel will NOT 22 * support the codes or instruction set in future products. 23 * 24 * Intel offers no warranty of any kind regarding the code. This code is 25 * licensed on an "AS IS" basis and Intel is not obligated to provide 26 * any support, assistance, installation, training, or other services 27 * of any kind. Intel is also not obligated to provide any updates, 28 * enhancements or extensions. Intel specifically disclaims any warranty 29 * of merchantability, non-infringement, fitness for any particular 30 * purpose, and any other warranty. 31 * 32 * Further, Intel disclaims all liability of any kind, including but 33 * not limited to liability for infringement of any proprietary rights, 34 * relating to the use of the code, even if Intel is notified of the 35 * possibility of such liability. Except as expressly stated in an Intel 36 * license agreement provided with this code and agreed upon with Intel, 37 * no license, express or implied, by estoppel or otherwise, to any 38 * intellectual property rights is granted herein. 39 */ 40 41 #ifndef _COIBUFFER_SINK_H 42 #define _COIBUFFER_SINK_H 43 44 /** @ingroup COIBuffer 45 * @addtogroup COIBufferSink 46 @{ 47 48 * @file sink\COIBuffer_sink.h 49 */ 50 #ifndef DOXYGEN_SHOULD_SKIP_THIS 51 #include "../common/COITypes_common.h" 52 #include "../common/COIResult_common.h" 53 #endif // DOXYGEN_SHOULD_SKIP_THIS 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 ////////////////////////////////////////////////////////////////////////////// 60 /// 61 /// Adds a reference to the memory of a buffer. The memory of the buffer 62 /// will remain on the device until both a corresponding COIBufferReleaseRef() 63 /// call is made and the run function that delivered the buffer returns. 64 /// 65 /// Running this API in a thread spawned within the run function is not 66 /// supported and will cause unpredictable results and may cause data corruption. 67 /// 68 /// @warning 1.It is possible for enqueued run functions to be unable to 69 /// execute due to all card memory being occupied by AddRef'd 70 /// buffers. As such, it is important that whenever a buffer is 71 /// AddRef'd that there be no dependencies on future run functions 72 /// for progress to be made towards releasing the buffer. 73 /// 2.It is important that AddRef is called within the scope of 74 /// run function that carries the buffer to be AddRef'd. 75 /// 76 /// @param in_pBuffer 77 /// [in] Pointer to the start of a buffer being AddRef'd, that was 78 /// passed in at the start of the run function. 79 /// 80 /// @return COI_SUCCESS if the buffer ref count was successfully incremented. 81 /// 82 /// @return COI_INVALID_POINTER if the buffer pointer is NULL. 83 /// 84 /// @return COI_INVALID_HANDLE if the buffer pointer is invalid. 85 /// 86 COIRESULT 87 COIBufferAddRef( 88 void *in_pBuffer); 89 90 91 ////////////////////////////////////////////////////////////////////////////// 92 /// 93 /// Removes a reference to the memory of a buffer. The memory of the buffer 94 /// will be eligible for being freed on the device when the following 95 /// conditions are met: the run function that delivered the buffer 96 /// returns, and the number of calls to COIBufferReleaseRef() matches the 97 /// number of calls to COIBufferAddRef(). 98 // 99 /// Running this API in a thread spawned within the run function is not 100 /// supported and will cause unpredictable results and may cause data corruption. 101 /// 102 /// @warning When a buffer is AddRef'd it is assumed that it is in use and all 103 /// other operations on that buffer waits for ReleaseRef() to happen. 104 /// So you cannot pass the AddRef'd buffer's handle to RunFunction 105 /// that calls ReleaseRef(). This is a circular dependency and will 106 /// cause a deadlock. Buffer's pointer (buffer's sink side 107 /// address/pointer which is different than source side BUFFER handle) 108 /// needs to be stored somewhere to retrieve it later to use in 109 /// ReleaseRef. 110 /// 111 /// @param in_pBuffer 112 /// [in] Pointer to the start of a buffer previously AddRef'd, that 113 /// was passed in at the start of the run function. 114 /// 115 /// @return COI_SUCCESS if the buffer refcount was successfully decremented. 116 /// 117 /// @return COI_INVALID_POINTER if the buffer pointer was invalid. 118 /// 119 /// @return COI_INVALID_HANDLE if the buffer did not have COIBufferAddRef() 120 /// previously called on it. 121 /// 122 COIRESULT 123 COIBufferReleaseRef( 124 void *in_pBuffer); 125 126 127 #ifdef __cplusplus 128 } /* extern "C" */ 129 #endif 130 131 #endif /* _COIBUFFER_SINK_H */ 132 133 /*! @} */ 134