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