0
# Memory Management and Data Transfer
1

2
Comprehensive memory management including buffer creation, image handling, data transfer between host and device, and advanced shared virtual memory (SVM) support for zero-copy operations in OpenCL 2.0+.
3

4
## Capabilities
5

6
### Buffer Management
7

8
Create and manage device memory buffers for data storage and computation.
9

10
```python { .api }
11
class Buffer:
12
    """
13
    OpenCL memory buffer for device data storage.
14
    
15
    Attributes:
16
    - size (int): Buffer size in bytes
17
    - context (Context): Associated OpenCL context
18
    """
19
    
20
    def __init__(self, context, flags, size=0, hostbuf=None):
21
        """
22
        Create OpenCL buffer.
23
        
24
        Parameters:
25
        - context (Context): OpenCL context
26
        - flags (mem_flags): Memory flags (READ_ONLY, WRITE_ONLY, READ_WRITE, etc.)
27
        - size (int): Buffer size in bytes (required if hostbuf is None)
28
        - hostbuf (buffer, optional): Host buffer to copy data from
29
        """
30
    
31
    def get_info(self, param):
32
        """Get buffer information."""
33

34
class LocalMemory:
35
    """
36
    Specification for kernel local memory allocation.
37
    """
38
    
39
    def __init__(self, size):
40
        """
41
        Specify local memory size for kernel.
42
        
43
        Parameters:
44
        - size (int): Local memory size in bytes
45
        """
46
```
47

48
### Image Handling
49

50
Create and manipulate image objects for texture operations and image processing.
51

52
```python { .api }
53
def create_image(context, flags, format, shape=None, pitches=None,
54
                hostbuf=None, is_array=False, buffer=None):
55
    """
56
    Create OpenCL image object.
57
    
58
    Parameters:
59
    - context (Context): OpenCL context
60
    - flags (mem_flags): Memory flags
61
    - format (ImageFormat): Image format specification
62
    - shape (tuple[int, ...], optional): Image dimensions (width, height, depth)
63
    - pitches (tuple[int, ...], optional): Row/slice pitch in bytes
64
    - hostbuf (buffer, optional): Host image data
65
    - is_array (bool): Whether to create image array
66
    - buffer (Buffer, optional): Buffer to create image from
67
    
68
    Returns:
69
    Image: Created image object
70
    """
71

72
def image_from_array(ctx, ary, num_channels=None, mode="r", norm_int=False):
73
    """
74
    Create image from numpy array.
75
    
76
    Parameters:
77
    - ctx (Context): OpenCL context
78
    - ary (numpy.ndarray): Source array (must be C-contiguous)
79
    - num_channels (int, optional): Number of channels (auto-detected if None)
80
    - mode (str): Access mode ("r" for read-only, "w" for write-only)
81
    - norm_int (bool): Use normalized integer format
82
    
83
    Returns:
84
    Image: Image object created from array
85
    """
86

87
class Image:
88
    """
89
    OpenCL image object for texture operations.
90
    
91
    Attributes:
92
    - format (ImageFormat): Image format
93
    - width (int): Image width  
94
    - height (int): Image height
95
    - depth (int): Image depth (for 3D images)
96
    """
97
    
98
    def get_info(self, param):
99
        """Get image information."""
100

101
class ImageFormat:
102
    """
103
    Specification for image channel order and data type.
104
    """
105
    
106
    def __init__(self, channel_order, channel_type):
107
        """
108
        Create image format.
109
        
110
        Parameters:
111
        - channel_order (channel_order): Channel ordering (R, RG, RGBA, etc.)
112
        - channel_type (channel_type): Data type (FLOAT, SIGNED_INT32, etc.)
113
        """
114

115
def get_supported_image_formats(context, flags, image_type):
116
    """
117
    Get supported image formats for context.
118
    
119
    Parameters:
120
    - context (Context): OpenCL context
121
    - flags (mem_flags): Memory flags
122
    - image_type (mem_object_type): Image type (IMAGE2D, IMAGE3D, etc.)
123
    
124
    Returns:
125
    list[ImageFormat]: Supported image formats
126
    """
127
```
128

129
### Data Transfer Operations
130

131
Transfer data between host and device memory with support for blocking and non-blocking operations.
132

133
```python { .api }
134
def enqueue_copy(queue, dest, src, **kwargs):
135
    """
136
    Universal copy function for host/device data transfer.
137
    
138
    Supports multiple transfer types:
139
    - Buffer ↔ Host: Linear data transfer
140
    - Buffer ↔ Buffer: Device-to-device copy
141
    - Image ↔ Host: Image data transfer
142
    - Image ↔ Buffer: Image/buffer conversion
143
    - Rectangular transfers: Sub-region copying
144
    
145
    Parameters:
146
    - queue (CommandQueue): Command queue
147
    - dest: Destination (Buffer, Image, or host array)
148
    - src: Source (Buffer, Image, or host array)
149
    - src_offset (int, optional): Source offset in bytes
150
    - dst_offset (int, optional): Destination offset in bytes
151
    - byte_count (int, optional): Number of bytes to copy
152
    - origin (tuple, optional): Origin for image/rectangular transfers
153
    - region (tuple, optional): Region size for image/rectangular transfers
154
    - is_blocking (bool): Wait for completion (default True)
155
    - wait_for (list[Event], optional): Events to wait for
156
    
157
    Returns:
158
    Event: Transfer completion event
159
    """
160

161
def enqueue_fill(queue, dest, pattern, size, *, offset=0, wait_for=None):
162
    """
163
    Fill memory with repeating pattern.
164
    
165
    Parameters:
166
    - queue (CommandQueue): Command queue
167
    - dest (Buffer | SVMPointer): Target memory
168
    - pattern (buffer): Fill pattern
169
    - size (int): Number of bytes to fill
170
    - offset (int): Offset in destination
171
    - wait_for (list[Event], optional): Events to wait for
172
    
173
    Returns:
174
    Event: Fill completion event
175
    """
176

177
def enqueue_fill_buffer(queue, mem, pattern, offset, size, wait_for=None):
178
    """
179
    Fill buffer with pattern.
180
    
181
    Parameters:
182
    - queue (CommandQueue): Command queue
183
    - mem (Buffer): Target buffer
184
    - pattern (buffer): Fill pattern
185
    - offset (int): Offset in buffer
186
    - size (int): Number of bytes to fill
187
    - wait_for (list[Event], optional): Events to wait for
188
    
189
    Returns:
190
    Event: Fill completion event
191
    """
192

193
def enqueue_fill_image(queue, mem, color, origin, region, wait_for=None):
194
    """
195
    Fill image with solid color.
196
    
197
    Parameters:
198
    - queue (CommandQueue): Command queue
199
    - mem (Image): Target image
200
    - color (buffer): Fill color matching image format
201
    - origin (tuple[int, ...]): Origin coordinates (x, y, z)
202
    - region (tuple[int, ...]): Region size (width, height, depth)
203
    - wait_for (list[Event], optional): Events to wait for
204
    
205
    Returns:
206
    Event: Fill completion event
207
    """
208

209
def enqueue_migrate_mem_objects(queue, mem_objects, flags=0, wait_for=None):
210
    """
211
    Migrate memory objects between devices.
212
    
213
    Useful for multi-device scenarios to optimize memory locality.
214
    
215
    Parameters:
216
    - queue (CommandQueue): Command queue
217
    - mem_objects (list[Buffer | Image]): Memory objects to migrate
218
    - flags (mem_migration_flags): Migration flags (HOST, CONTENT_UNDEFINED)
219
    - wait_for (list[Event], optional): Events to wait for
220
    
221
    Returns:
222
    Event: Migration completion event
223
    """
224
```
225

226
### Memory Mapping
227

228
Map device memory to host address space for direct access.
229

230
```python { .api }
231
class MemoryMap:
232
    """
233
    Context manager for mapped memory regions.
234
    """
235
    
236
    def __enter__(self):
237
        """Enter mapping context, returns host pointer."""
238
    
239
    def __exit__(self, exc_type, exc_val, exc_tb):
240
        """Exit mapping context, unmaps memory."""
241
    
242
    def release(self, queue=None, wait_for=None):
243
        """
244
        Explicitly unmap memory.
245
        
246
        Parameters:
247
        - queue (CommandQueue, optional): Command queue
248
        - wait_for (list[Event], optional): Events to wait for
249
        
250
        Returns:
251
        Event: Unmap completion event
252
        """
253

254
def enqueue_map_buffer(queue, buf, flags, offset, shape, dtype, order="C", 
255
                      strides=None, wait_for=None, is_blocking=True):
256
    """
257
    Map buffer memory to host address space for direct access.
258
    
259
    Parameters:
260
    - queue (CommandQueue): Command queue
261
    - buf (Buffer): Buffer to map
262
    - flags (map_flags): Mapping flags (READ, WRITE, READ_WRITE)
263
    - offset (int): Offset in buffer
264
    - shape (tuple[int, ...]): Shape of mapped region
265
    - dtype: NumPy data type for array view
266
    - order (str): Memory order ("C" or "F")
267
    - strides (tuple[int, ...], optional): Custom strides
268
    - wait_for (list[Event], optional): Events to wait for
269
    - is_blocking (bool): Wait for mapping completion
270
    
271
    Returns:
272
    MemoryMap: Memory mapping context manager
273
    """
274

275
def enqueue_map_image(queue, img, flags, origin, region, shape, dtype,
276
                     order="C", strides=None, wait_for=None, is_blocking=True):
277
    """
278
    Map image memory to host address space for direct access.
279
    
280
    Parameters:
281
    - queue (CommandQueue): Command queue
282
    - img (Image): Image to map
283
    - flags (map_flags): Mapping flags (READ, WRITE, READ_WRITE)
284
    - origin (tuple[int, ...]): Origin coordinates (x, y, z)
285
    - region (tuple[int, ...]): Region size (width, height, depth)
286
    - shape (tuple[int, ...]): Shape of mapped array
287
    - dtype: NumPy data type for array view
288
    - order (str): Memory order ("C" or "F")
289
    - strides (tuple[int, ...], optional): Custom strides
290
    - wait_for (list[Event], optional): Events to wait for
291
    - is_blocking (bool): Wait for mapping completion
292
    
293
    Returns:
294
    MemoryMap: Memory mapping context manager
295
    """
296
```
297

298
### Shared Virtual Memory (OpenCL 2.0+)
299

300
Zero-copy memory sharing between host and device using shared virtual memory.
301

302
```python { .api }
303
class SVM:
304
    """
305
    Shared Virtual Memory pointer wrapper.
306
    """
307
    
308
    def __init__(self, data):
309
        """
310
        Wrap host data as SVM pointer.
311
        
312
        Parameters:
313
        - data: Host data with buffer interface
314
        """
315

316
class SVMPointer:
317
    """
318
    Base class for SVM pointer implementations.
319
    """
320

321
class SVMAllocation:
322
    """
323
    SVM memory allocation with device access.
324
    """
325
    
326
    def __init__(self, ctx, size, alignment, flags, queue=None):
327
        """
328
        Allocate SVM memory.
329
        
330
        Parameters:
331
        - ctx (Context): OpenCL context
332
        - size (int): Allocation size in bytes
333
        - alignment (int): Memory alignment
334
        - flags (svm_mem_flags): SVM memory flags
335
        - queue (CommandQueue, optional): Associated queue
336
        """
337

338
class SVMMap:
339
    """
340
    Context manager for SVM memory mapping.
341
    
342
    Attributes:
343
    - array: Mapped array object
344
    - event (Event): Mapping event
345
    """
346
    
347
    def __enter__(self):
348
        """Enter mapping context."""
349
    
350
    def __exit__(self, exc_type, exc_val, exc_tb):
351
        """Exit mapping context."""
352
    
353
    def release(self, queue=None, wait_for=None):
354
        """
355
        Release SVM mapping.
356
        
357
        Parameters:
358
        - queue (CommandQueue, optional): Command queue
359
        - wait_for (list[Event], optional): Events to wait for
360
        
361
        Returns:
362
        Event: Release completion event
363
        """
364

365
def svm_empty(ctx, flags, shape, dtype, order="C", alignment=None, queue=None):
366
    """
367
    Allocate empty SVM array.
368
    
369
    Parameters:
370
    - ctx (Context): OpenCL context
371
    - flags (svm_mem_flags): SVM memory flags
372
    - shape (int | tuple[int, ...]): Array shape
373
    - dtype: NumPy data type
374
    - order (str): Memory layout ("C" or "F")
375
    - alignment (int, optional): Memory alignment
376
    - queue (CommandQueue, optional): Associated queue
377
    
378
    Returns:
379
    numpy.ndarray: SVM-backed array
380
    """
381

382
def svm_empty_like(ctx, flags, ary, alignment=None):
383
    """
384
    Allocate SVM array like existing array.
385
    
386
    Parameters:
387
    - ctx (Context): OpenCL context
388
    - flags (svm_mem_flags): SVM memory flags
389
    - ary (numpy.ndarray): Template array
390
    - alignment (int, optional): Memory alignment
391
    
392
    Returns:
393
    numpy.ndarray: SVM-backed array
394
    """
395

396
def csvm_empty(ctx, shape, dtype, order="C", alignment=None, queue=None):
397
    """
398
    Allocate coarse-grain SVM array (convenience function).
399
    
400
    Parameters:
401
    - ctx (Context): OpenCL context
402
    - shape (int | tuple[int, ...]): Array shape
403
    - dtype: NumPy data type
404
    - order (str): Memory layout
405
    - alignment (int, optional): Memory alignment
406
    - queue (CommandQueue, optional): Associated queue
407
    
408
    Returns:
409
    numpy.ndarray: Coarse-grain SVM array
410
    """
411

412
def fsvm_empty(ctx, shape, dtype, order="C", alignment=None, queue=None):
413
    """
414
    Allocate fine-grain SVM array (convenience function).
415
    
416
    Parameters:
417
    - ctx (Context): OpenCL context
418
    - shape (int | tuple[int, ...]): Array shape
419
    - dtype: NumPy data type
420
    - order (str): Memory layout
421
    - alignment (int, optional): Memory alignment
422
    - queue (CommandQueue, optional): Associated queue
423
    
424
    Returns:
425
    numpy.ndarray: Fine-grain SVM array
426
    """
427

428
def enqueue_svm_memfill(queue, dest, pattern, byte_count=None, wait_for=None):
429
    """
430
    Fill SVM memory with pattern.
431
    
432
    Parameters:
433
    - queue (CommandQueue): Command queue
434
    - dest (SVMPointer): Target SVM memory
435
    - pattern (buffer): Fill pattern
436
    - byte_count (int, optional): Bytes to fill (default: entire dest)
437
    - wait_for (list[Event], optional): Events to wait for
438
    
439
    Returns:
440
    Event: Fill completion event
441
    """
442

443
def enqueue_svm_migrate_mem(queue, svms, flags, wait_for=None):
444
    """
445
    Migrate SVM memory between devices (OpenCL 2.1).
446
    
447
    Parameters:
448
    - queue (CommandQueue): Command queue
449
    - svms (list[SVMPointer]): SVM objects to migrate
450
    - flags (mem_migration_flags): Migration flags
451
    - wait_for (list[Event], optional): Events to wait for
452
    
453
    Returns:
454
    Event: Migration completion event
455
    """
456
```
457

458
### Sampler Objects
459

460
Configure texture sampling for image operations.
461

462
```python { .api }
463
class Sampler:
464
    """
465
    Texture sampler for image operations.
466
    """
467
    
468
    def __init__(self, context, normalized_coords, addressing_mode, filter_mode):
469
        """
470
        Create texture sampler.
471
        
472
        Parameters:
473
        - context (Context): OpenCL context
474
        - normalized_coords (bool): Use normalized coordinates
475
        - addressing_mode (addressing_mode): Address handling (CLAMP, REPEAT, etc.)
476
        - filter_mode (filter_mode): Filtering (NEAREST, LINEAR)
477
        """
478
```
479

480
## Usage Examples
481

482
### Basic Buffer Operations
483

484
```python
485
import pyopencl as cl
486
import numpy as np
487

488
# Setup
489
ctx = cl.create_some_context()
490
queue = cl.CommandQueue(ctx)
491

492
# Create host data
493
data = np.random.randn(1000).astype(np.float32)
494

495
# Create buffer and copy data
496
buf = cl.Buffer(ctx, cl.mem_flags.READ_WRITE | cl.mem_flags.COPY_HOST_PTR, hostbuf=data)
497

498
# Modify data on device (kernel execution would go here)
499
# ...
500

501
# Copy back to host
502
result = np.empty_like(data)
503
cl.enqueue_copy(queue, result, buf)
504
```
505

506
### Image Processing Example
507

508
```python
509
import pyopencl as cl
510
import numpy as np
511

512
# Setup
513
ctx = cl.create_some_context()
514
queue = cl.CommandQueue(ctx)
515

516
# Create image from numpy array
517
image_data = np.random.randint(0, 256, (512, 512, 4), dtype=np.uint8)
518
image = cl.image_from_array(ctx, image_data, mode="r")
519

520
# Process image (kernel execution would go here)
521
# ...
522

523
# Read back processed image
524
result = np.empty_like(image_data)
525
cl.enqueue_copy(queue, result, image, origin=(0, 0), region=image_data.shape[:2])
526
```
527

528
### SVM Memory Usage
529

530
```python
531
import pyopencl as cl
532
import numpy as np
533

534
# Setup (requires OpenCL 2.0+)
535
ctx = cl.create_some_context()
536
queue = cl.CommandQueue(ctx)
537

538
# Check SVM support
539
if not cl.characterize.has_coarse_grain_buffer_svm(ctx.devices[0]):
540
    print("SVM not supported")
541
    exit()
542

543
# Allocate SVM memory
544
svm_data = cl.csvm_empty(ctx, (1000,), np.float32)
545

546
# Fill with data
547
svm_data[:] = np.random.randn(1000).astype(np.float32)
548

549
# Use in kernel (both host and device can access)
550
# kernel execution would use SVM(svm_data) as argument
551
# ...
552

553
print(f"SVM data: {svm_data[:5]}")
554
```
555

556
### Memory Mapping
557

558
```python
559
import pyopencl as cl
560
import numpy as np
561

562
# Setup
563
ctx = cl.create_some_context()
564
queue = cl.CommandQueue(ctx)
565

566
# Create buffer
567
size = 1000 * np.dtype(np.float32).itemsize
568
buf = cl.Buffer(ctx, cl.mem_flags.READ_WRITE, size)
569

570
# Map buffer for host access
571
with cl.enqueue_map_buffer(queue, buf, cl.map_flags.READ | cl.map_flags.WRITE, 
572
                          0, size, np.float32) as mapped:
573
    # Direct access to device memory
574
    mapped[:] = np.random.randn(1000).astype(np.float32)
575
    print(f"Mapped data: {mapped[:5]}")
576

577
# Buffer automatically unmapped when leaving 'with' block
578
```