1/* 2 * Copyright 2010-2013 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 56extern "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/// Intel�� Coprocessor Offload Infrastructure (Intel�� COI) streaming buffers should not be AddRef'd. Doing so may result in 66/// unpredictable results or may cause the sink process to crash. 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'ed 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'ed. 75/// 76/// @param in_pBuffer 77/// [in] Pointer to the start of a buffer being addref'ed, 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/// 86COIRESULT 87COIBufferAddRef( 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/// @warning When a buffer is addref'ed it is assumed that it is in use and all 100/// other operations on that buffer waits for ReleaseRef() to happen. 101/// So you cannot pass the addref'ed buffer's handle to RunFunction 102/// that calls ReleaseRef(). This is a circular dependency and will 103/// cause a deadlock. Buffer's pointer (buffer's sink side 104/// address/pointer which is different than source side BUFFER handle) 105/// needs to be stored somewhere to retrieve it later to use in 106/// ReleaseRef. 107/// 108/// @param in_pBuffer 109/// [in] Pointer to the start of a buffer previously addref'ed, that 110/// was passed in at the start of the run function. 111/// 112/// @return COI_SUCCESS if the buffer refcount was successfully decremented. 113/// 114/// @return COI_INVALID_POINTER if the buffer pointer was invalid. 115/// 116/// @return COI_INVALID_HANDLE if the buffer did not have COIBufferAddRef() 117/// previously called on it. 118/// 119COIRESULT 120COIBufferReleaseRef( 121 void* in_pBuffer); 122 123 124#ifdef __cplusplus 125} /* extern "C" */ 126#endif 127 128#endif /* _COIBUFFER_SINK_H */ 129 130/*! @} */ 131