Compute Library
 21.05
CLTensorAllocator.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2021 Arm Limited.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all
14  * copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24 #ifndef ARM_COMPUTE_CLTENSORALLOCATOR_H
25 #define ARM_COMPUTE_CLTENSORALLOCATOR_H
26 
32 
35 
36 #include <cstdint>
37 
38 namespace arm_compute
39 {
40 class CLTensor;
41 class CLRuntimeContext;
42 /** Basic implementation of a CL memory tensor allocator. */
44 {
45 public:
46  /** Default constructor.
47  *
48  * @param[in] owner (Optional) Owner of the allocator.
49  * @param[in] ctx (Optional) Runtime context.
50  */
51  CLTensorAllocator(IMemoryManageable *owner = nullptr, CLRuntimeContext *ctx = nullptr);
52  /** Prevent instances of this class from being copied (As this class contains pointers) */
53  CLTensorAllocator(const CLTensorAllocator &) = delete;
54  /** Prevent instances of this class from being copy assigned (As this class contains pointers) */
56  /** Allow instances of this class to be moved */
58  /** Allow instances of this class to be moved */
60 
61  /** Interface to be implemented by the child class to return the pointer to the mapped data.
62  *
63  * @return pointer to the mapped data.
64  */
65  uint8_t *data();
66  /** Interface to be implemented by the child class to return the pointer to the CL data.
67  *
68  * @return pointer to the CL data.
69  */
70  const cl::Buffer &cl_data() const;
71  /** Wrapped quantization info data accessor
72  *
73  * @return A wrapped quantization info object.
74  */
76 
77  /** Enqueue a map operation of the allocated buffer on the given queue.
78  *
79  * @param[in,out] q The CL command queue to use for the mapping operation.
80  * @param[in] blocking If true, then the mapping will be ready to use by the time
81  * this method returns, else it is the caller's responsibility
82  * to flush the queue and wait for the mapping operation to have completed before using the returned mapping pointer.
83  *
84  * @return The mapping address.
85  */
86  uint8_t *map(cl::CommandQueue &q, bool blocking);
87  /** Enqueue an unmap operation of the allocated buffer on the given queue.
88  *
89  * @note This method simply enqueue the unmap operation, it is the caller's responsibility to flush the queue and make sure the unmap is finished before
90  * the memory is accessed by the device.
91  *
92  * @param[in,out] q The CL command queue to use for the mapping operation.
93  * @param[in] mapping The cpu mapping to unmap.
94  */
95  void unmap(cl::CommandQueue &q, uint8_t *mapping);
96 
97  /** Allocate size specified by TensorInfo of OpenCL memory.
98  *
99  * @note: The tensor must not already be allocated when calling this function.
100  *
101  */
102  void allocate() override;
103 
104  /** Free allocated OpenCL memory.
105  *
106  * @note The tensor must have been allocated when calling this function.
107  *
108  */
109  void free() override;
110  /** Import an existing memory as a tensor's backing memory
111  *
112  * @warning memory should have been created under the same context that Compute Library uses.
113  * @warning memory is expected to be aligned with the device requirements.
114  * @warning tensor shouldn't be memory managed.
115  * @warning ownership of memory is not transferred.
116  * @warning memory must be writable in case of in-place operations
117  * @warning padding should be accounted by the client code.
118  * @note buffer size will be checked to be compliant with total_size reported by ITensorInfo.
119  *
120  * @param[in] buffer Buffer to be used as backing memory
121  *
122  * @return An error status
123  */
124  Status import_memory(cl::Buffer buffer);
125  /** Associates the tensor with a memory group
126  *
127  * @param[in] associated_memory_group Memory group to associate the tensor with
128  */
129  void set_associated_memory_group(IMemoryGroup *associated_memory_group);
130 
131  /** Sets global allocator that will be used by all CLTensor objects
132  *
133  *
134  * @param[in] allocator Allocator to be used as a global allocator
135  */
137 
138 protected:
139  /** Call map() on the OpenCL buffer.
140  *
141  * @return A pointer to the beginning of the tensor's allocation.
142  */
143  uint8_t *lock() override;
144  /** Call unmap() on the OpenCL buffer. */
145  void unlock() override;
146 
147 private:
148  static const cl::Buffer _empty_buffer;
149 
150 private:
151  CLRuntimeContext *_ctx;
152  IMemoryManageable *_owner; /**< Memory manageable object that owns the allocator */
153  IMemoryGroup *_associated_memory_group; /**< Registered memory manager */
154  CLMemory _memory; /**< OpenCL memory */
155  uint8_t *_mapping; /**< Pointer to the CPU mapping of the OpenCL buffer. */
156  CLFloatArray _scale; /**< Scales array in case of quantized per channel data type */
157  CLInt32Array _offset; /**< Offsets array in case of quantized per channel data type */
158 };
159 } // namespace arm_compute
160 #endif /* ARM_COMPUTE_CLTENSORALLOCATOR_H */
Memory group interface.
Definition: IMemoryGroup.h:37
static void set_global_allocator(IAllocator *allocator)
Sets global allocator that will be used by all CLTensor objects.
CLQuantization quantization() const
Wrapped quantization info data accessor.
Status class.
Definition: Error.h:52
OpenCL quantization data.
Definition: CLTypes.h:62
Copyright (c) 2017-2021 Arm Limited.
Status import_memory(cl::Buffer buffer)
Import an existing memory as a tensor's backing memory.
Basic implementation of a CL memory tensor allocator.
void set_associated_memory_group(IMemoryGroup *associated_memory_group)
Associates the tensor with a memory group.
uint8_t * data()
Interface to be implemented by the child class to return the pointer to the mapped data.
uint8_t * map(cl::CommandQueue &q, bool blocking)
Enqueue a map operation of the allocated buffer on the given queue.
CLTensorAllocator(IMemoryManageable *owner=nullptr, CLRuntimeContext *ctx=nullptr)
Default constructor.
void unmap(cl::CommandQueue &q, uint8_t *mapping)
Enqueue an unmap operation of the allocated buffer on the given queue.
input allocator() -> allocate()
void allocate() override
Allocate size specified by TensorInfo of OpenCL memory.
Interface of an object than can be memory managed.
Definition: IMemoryGroup.h:69
OpenCL implementation of memory object.
Definition: CLMemory.h:38
const cl::Buffer & cl_data() const
Interface to be implemented by the child class to return the pointer to the CL data.
void free() override
Free allocated OpenCL memory.
Wrapper to configure the Khronos OpenCL C++ header.
Allocator interface.
Definition: IAllocator.h:35
CLTensorAllocator & operator=(const CLTensorAllocator &)=delete
Prevent instances of this class from being copy assigned (As this class contains pointers)
Interface to allocate tensors.