~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/gpu/drm-mm.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/gpu/drm-mm.rst (Version linux-6.12-rc7) and /Documentation/gpu/drm-mm.rst (Version ccs-tools-1.8.12)


  1 =====================                             
  2 DRM Memory Management                             
  3 =====================                             
  4                                                   
  5 Modern Linux systems require large amount of g    
  6 frame buffers, textures, vertices and other gr    
  7 the very dynamic nature of many of that data,     
  8 efficiently is thus crucial for the graphics s    
  9 role in the DRM infrastructure.                   
 10                                                   
 11 The DRM core includes two memory managers, nam    
 12 (TTM) and Graphics Execution Manager (GEM). TT    
 13 manager to be developed and tried to be a one-    
 14 solution. It provides a single userspace API t    
 15 all hardware, supporting both Unified Memory A    
 16 and devices with dedicated video RAM (i.e. mos    
 17 This resulted in a large, complex piece of cod    
 18 hard to use for driver development.               
 19                                                   
 20 GEM started as an Intel-sponsored project in r    
 21 complexity. Its design philosophy is completel    
 22 providing a solution to every graphics memory-    
 23 identified common code between drivers and cre    
 24 share it. GEM has simpler initialization and e    
 25 TTM, but has no video RAM management capabilit    
 26 UMA devices.                                      
 27                                                   
 28 The Translation Table Manager (TTM)               
 29 ===================================               
 30                                                   
 31 .. kernel-doc:: drivers/gpu/drm/ttm/ttm_module    
 32    :doc: TTM                                      
 33                                                   
 34 .. kernel-doc:: include/drm/ttm/ttm_caching.h     
 35    :internal:                                     
 36                                                   
 37 TTM device object reference                       
 38 ---------------------------                       
 39                                                   
 40 .. kernel-doc:: include/drm/ttm/ttm_device.h      
 41    :internal:                                     
 42                                                   
 43 .. kernel-doc:: drivers/gpu/drm/ttm/ttm_device    
 44    :export:                                       
 45                                                   
 46 TTM resource placement reference                  
 47 --------------------------------                  
 48                                                   
 49 .. kernel-doc:: include/drm/ttm/ttm_placement.    
 50    :internal:                                     
 51                                                   
 52 TTM resource object reference                     
 53 -----------------------------                     
 54                                                   
 55 .. kernel-doc:: include/drm/ttm/ttm_resource.h    
 56    :internal:                                     
 57                                                   
 58 .. kernel-doc:: drivers/gpu/drm/ttm/ttm_resour    
 59    :export:                                       
 60                                                   
 61 TTM TT object reference                           
 62 -----------------------                           
 63                                                   
 64 .. kernel-doc:: include/drm/ttm/ttm_tt.h          
 65    :internal:                                     
 66                                                   
 67 .. kernel-doc:: drivers/gpu/drm/ttm/ttm_tt.c      
 68    :export:                                       
 69                                                   
 70 TTM page pool reference                           
 71 -----------------------                           
 72                                                   
 73 .. kernel-doc:: include/drm/ttm/ttm_pool.h        
 74    :internal:                                     
 75                                                   
 76 .. kernel-doc:: drivers/gpu/drm/ttm/ttm_pool.c    
 77    :export:                                       
 78                                                   
 79 The Graphics Execution Manager (GEM)              
 80 ====================================              
 81                                                   
 82 The GEM design approach has resulted in a memo    
 83 provide full coverage of all (or even all comm    
 84 userspace or kernel API. GEM exposes a set of     
 85 operations to userspace and a set of helper fu    
 86 let drivers implement hardware-specific operat    
 87 private API.                                      
 88                                                   
 89 The GEM userspace API is described in the `GEM    
 90 Manager <http://lwn.net/Articles/283798/>`__ a    
 91 slightly outdated, the document provides a goo    
 92 principles. Buffer allocation and read and wri    
 93 as part of the common GEM API, are currently i    
 94 driver-specific ioctls.                           
 95                                                   
 96 GEM is data-agnostic. It manages abstract buff    
 97 what individual buffers contain. APIs that req    
 98 contents or purpose, such as buffer allocation    
 99 primitives, are thus outside of the scope of G    
100 using driver-specific ioctls.                     
101                                                   
102 On a fundamental level, GEM involves several o    
103                                                   
104 -  Memory allocation and freeing                  
105 -  Command execution                              
106 -  Aperture management at command execution ti    
107                                                   
108 Buffer object allocation is relatively straigh    
109 provided by Linux's shmem layer, which provide    
110 object.                                           
111                                                   
112 Device-specific operations, such as command ex    
113 read & write, mapping, and domain ownership tr    
114 driver-specific ioctls.                           
115                                                   
116 GEM Initialization                                
117 ------------------                                
118                                                   
119 Drivers that use GEM must set the DRIVER_GEM b    
120 :c:type:`struct drm_driver <drm_driver>` drive    
121 field. The DRM core will then automatically in    
122 before calling the load operation. Behind the     
123 DRM Memory Manager object which provides an ad    
124 object allocation.                                
125                                                   
126 In a KMS configuration, drivers need to alloca    
127 command ring buffer following core GEM initial    
128 hardware. UMA devices usually have what is cal    
129 region, which provides space for the initial f    
130 contiguous memory regions required by the devi    
131 typically not managed by GEM, and must be init    
132 its own DRM MM object.                            
133                                                   
134 GEM Objects Creation                              
135 --------------------                              
136                                                   
137 GEM splits creation of GEM objects and allocat    
138 backs them in two distinct operations.            
139                                                   
140 GEM objects are represented by an instance of     
141 drm_gem_object <drm_gem_object>`. Drivers usua    
142 extend GEM objects with private information an    
143 driver-specific GEM object structure type that    
144 struct :c:type:`struct drm_gem_object <drm_gem    
145                                                   
146 To create a GEM object, a driver allocates mem    
147 specific GEM object type and initializes the e    
148 :c:type:`struct drm_gem_object <drm_gem_object    
149 to drm_gem_object_init(). The function takes a    
150 to the DRM device, a pointer to the GEM object    
151 size in bytes.                                    
152                                                   
153 GEM uses shmem to allocate anonymous pageable     
154 drm_gem_object_init() will create an shmfs fil    
155 requested size and store it into the struct :c    
156 drm_gem_object <drm_gem_object>` filp field. T    
157 used as either main storage for the object whe    
158 uses system memory directly or as a backing st    
159                                                   
160 Drivers are responsible for the actual physica    
161 calling shmem_read_mapping_page_gfp() for each    
162 Note that they can decide to allocate pages wh    
163 object, or to delay allocation until the memor    
164 when a page fault occurs as a result of a user    
165 when the driver needs to start a DMA transfer     
166                                                   
167 Anonymous pageable memory allocation is not al    
168 when the hardware requires physically contiguo    
169 often the case in embedded devices. Drivers ca    
170 no shmfs backing (called private GEM objects)     
171 to drm_gem_private_object_init() instead of dr    
172 private GEM objects must be managed by drivers    
173                                                   
174 GEM Objects Lifetime                              
175 --------------------                              
176                                                   
177 All GEM objects are reference-counted by the G    
178 acquired and release by calling drm_gem_object    
179 respectively.                                     
180                                                   
181 When the last reference to a GEM object is rel    
182 the :c:type:`struct drm_gem_object_funcs <gem_    
183 operation. That operation is mandatory for GEM    
184 free the GEM object and all associated resourc    
185                                                   
186 void (\*free) (struct drm_gem_object \*obj); D    
187 responsible for freeing all GEM object resourc    
188 resources created by the GEM core, which need     
189 drm_gem_object_release().                         
190                                                   
191 GEM Objects Naming                                
192 ------------------                                
193                                                   
194 Communication between userspace and the kernel    
195 using local handles, global names or, more rec    
196 All of those are 32-bit integer values; the us    
197 apply to the file descriptors.                    
198                                                   
199 GEM handles are local to a DRM file. Applicati    
200 object through a driver-specific ioctl, and ca    
201 to the GEM object in other standard or driver-    
202 DRM file handle frees all its GEM handles and     
203 associated GEM objects.                           
204                                                   
205 To create a handle for a GEM object drivers ca    
206 function takes a pointer to the DRM file and t    
207 locally unique handle.  When the handle is no     
208 with a call to drm_gem_handle_delete(). Finall    
209 handle can be retrieved by a call to drm_gem_o    
210                                                   
211 Handles don't take ownership of GEM objects, t    
212 to the object that will be dropped when the ha    
213 avoid leaking GEM objects, drivers must make s    
214 reference(s) they own (such as the initial ref    
215 creation time) as appropriate, without any spe    
216 handle. For example, in the particular case of    
217 handle creation in the implementation of the d    
218 drivers must drop the initial reference to the    
219 returning the handle.                             
220                                                   
221 GEM names are similar in purpose to handles bu    
222 files. They can be passed between processes to    
223 globally. Names can't be used directly to refe    
224 API, applications must convert handles to name    
225 using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GE    
226 respectively. The conversion is handled by the    
227 driver-specific support.                          
228                                                   
229 GEM also supports buffer sharing with dma-buf     
230 PRIME. GEM-based drivers must use the provided    
231 implement the exporting and importing correctl    
232 file descriptors is inherently more secure tha    
233 global GEM names it is the preferred buffer sh    
234 buffers through GEM names is only supported fo    
235 Furthermore PRIME also allows cross-device buf    
236 based on dma-bufs.                                
237                                                   
238 GEM Objects Mapping                               
239 -------------------                               
240                                                   
241 Because mapping operations are fairly heavywei    
242 read/write-like access to buffers, implemented    
243 ioctls, over mapping buffers to userspace. How    
244 to the buffer is needed (to perform software r    
245 direct access to the object can be more effici    
246                                                   
247 The mmap system call can't be used directly to    
248 don't have their own file handle. Two alternat    
249 co-exist to map GEM objects to userspace. The     
250 driver-specific ioctl to perform the mapping o    
251 do_mmap() under the hood. This is often consid    
252 dubious, seems to be discouraged for new GEM-e    
253 thus not be described here.                       
254                                                   
255 The second method uses the mmap system call on    
256 \*mmap(void \*addr, size_t length, int prot, i    
257 offset); DRM identifies the GEM object to be m    
258 passed through the mmap offset argument. Prior    
259 object must thus be associated with a fake off    
260 must call drm_gem_create_mmap_offset() on the     
261                                                   
262 Once allocated, the fake offset value must be     
263 in a driver-specific way and can then be used     
264 argument.                                         
265                                                   
266 The GEM core provides a helper method drm_gem_    
267 handle object mapping. The method can be set d    
268 operation handler. It will look up the GEM obj    
269 value and set the VMA operations to the :c:typ    
270 <drm_driver>` gem_vm_ops field. Note that drm_    
271 userspace, but relies on the driver-provided f    
272 individually.                                     
273                                                   
274 To use drm_gem_mmap(), drivers must fill the s    
275 <drm_driver>` gem_vm_ops field with a pointer     
276                                                   
277 The VM operations is a :c:type:`struct vm_oper    
278 made up of several fields, the more interestin    
279                                                   
280 .. code-block:: c                                 
281                                                   
282         struct vm_operations_struct {             
283                 void (*open)(struct vm_area_st    
284                 void (*close)(struct vm_area_s    
285                 vm_fault_t (*fault)(struct vm_    
286         };                                        
287                                                   
288                                                   
289 The open and close operations must update the     
290 count. Drivers can use the drm_gem_vm_open() a    
291 functions directly as open and close handlers.    
292                                                   
293 The fault operation handler is responsible for    
294 to userspace when a page fault occurs. Dependi    
295 allocation scheme, drivers can allocate pages     
296 decide to allocate memory for the GEM object a    
297 created.                                          
298                                                   
299 Drivers that want to map the GEM object upfron    
300 faults can implement their own mmap file opera    
301                                                   
302 For platforms without MMU the GEM core provide    
303 drm_gem_dma_get_unmapped_area(). The mmap() ro    
304 proposed address for the mapping.                 
305                                                   
306 To use drm_gem_dma_get_unmapped_area(), driver    
307 :c:type:`struct file_operations <file_operatio    
308 a pointer on drm_gem_dma_get_unmapped_area().     
309                                                   
310 More detailed information about get_unmapped_a    
311 Documentation/admin-guide/mm/nommu-mmap.rst       
312                                                   
313 Memory Coherency                                  
314 ----------------                                  
315                                                   
316 When mapped to the device or used in a command    
317 an object are flushed to memory and marked wri    
318 coherent with the GPU. Likewise, if the CPU ac    
319 GPU has finished rendering to the object, then    
320 coherent with the CPU's view of memory, usuall    
321 flushing of various kinds. This core CPU<->GPU    
322 provided by a device-specific ioctl, which eva    
323 domain and performs any necessary flushing or     
324 object into the desired coherency domain (note    
325 busy, i.e. an active render target; in that ca    
326 blocks the client and waits for rendering to c    
327 any necessary flushing operations).               
328                                                   
329 Command Execution                                 
330 -----------------                                 
331                                                   
332 Perhaps the most important GEM function for GP    
333 command execution interface to clients. Client    
334 command buffers containing references to previ    
335 objects, and then submit them to GEM. At that     
336 bind all the objects into the GTT, execute the    
337 necessary synchronization between clients acce    
338 This often involves evicting some objects from    
339 others (a fairly expensive operation), and pro    
340 which hides fixed GTT offsets from clients. Cl    
341 to submit command buffers that reference more     
342 the GTT; otherwise, GEM will reject them and n    
343 Similarly, if several objects in the buffer re    
344 be allocated for correct rendering (e.g. 2D bl    
345 care must be taken not to require more fence r    
346 available to the client. Such resource managem    
347 from the client in libdrm.                        
348                                                   
349 GEM Function Reference                            
350 ----------------------                            
351                                                   
352 .. kernel-doc:: include/drm/drm_gem.h             
353    :internal:                                     
354                                                   
355 .. kernel-doc:: drivers/gpu/drm/drm_gem.c         
356    :export:                                       
357                                                   
358 GEM DMA Helper Functions Reference                
359 ----------------------------------                
360                                                   
361 .. kernel-doc:: drivers/gpu/drm/drm_gem_dma_he    
362    :doc: dma helpers                              
363                                                   
364 .. kernel-doc:: include/drm/drm_gem_dma_helper    
365    :internal:                                     
366                                                   
367 .. kernel-doc:: drivers/gpu/drm/drm_gem_dma_he    
368    :export:                                       
369                                                   
370 GEM SHMEM Helper Function Reference               
371 -----------------------------------               
372                                                   
373 .. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_    
374    :doc: overview                                 
375                                                   
376 .. kernel-doc:: include/drm/drm_gem_shmem_help    
377    :internal:                                     
378                                                   
379 .. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_    
380    :export:                                       
381                                                   
382 GEM VRAM Helper Functions Reference               
383 -----------------------------------               
384                                                   
385 .. kernel-doc:: drivers/gpu/drm/drm_gem_vram_h    
386    :doc: overview                                 
387                                                   
388 .. kernel-doc:: include/drm/drm_gem_vram_helpe    
389    :internal:                                     
390                                                   
391 .. kernel-doc:: drivers/gpu/drm/drm_gem_vram_h    
392    :export:                                       
393                                                   
394 GEM TTM Helper Functions Reference                
395 -----------------------------------               
396                                                   
397 .. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_he    
398    :doc: overview                                 
399                                                   
400 .. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_he    
401    :export:                                       
402                                                   
403 VMA Offset Manager                                
404 ==================                                
405                                                   
406 .. kernel-doc:: drivers/gpu/drm/drm_vma_manage    
407    :doc: vma offset manager                       
408                                                   
409 .. kernel-doc:: include/drm/drm_vma_manager.h     
410    :internal:                                     
411                                                   
412 .. kernel-doc:: drivers/gpu/drm/drm_vma_manage    
413    :export:                                       
414                                                   
415 .. _prime_buffer_sharing:                         
416                                                   
417 PRIME Buffer Sharing                              
418 ====================                              
419                                                   
420 PRIME is the cross device buffer sharing frame    
421 created for the OPTIMUS range of multi-gpu pla    
422 buffers are dma-buf based file descriptors.       
423                                                   
424 Overview and Lifetime Rules                       
425 ---------------------------                       
426                                                   
427 .. kernel-doc:: drivers/gpu/drm/drm_prime.c       
428    :doc: overview and lifetime rules              
429                                                   
430 PRIME Helper Functions                            
431 ----------------------                            
432                                                   
433 .. kernel-doc:: drivers/gpu/drm/drm_prime.c       
434    :doc: PRIME Helpers                            
435                                                   
436 PRIME Function References                         
437 -------------------------                         
438                                                   
439 .. kernel-doc:: include/drm/drm_prime.h           
440    :internal:                                     
441                                                   
442 .. kernel-doc:: drivers/gpu/drm/drm_prime.c       
443    :export:                                       
444                                                   
445 DRM MM Range Allocator                            
446 ======================                            
447                                                   
448 Overview                                          
449 --------                                          
450                                                   
451 .. kernel-doc:: drivers/gpu/drm/drm_mm.c          
452    :doc: Overview                                 
453                                                   
454 LRU Scan/Eviction Support                         
455 -------------------------                         
456                                                   
457 .. kernel-doc:: drivers/gpu/drm/drm_mm.c          
458    :doc: lru scan roster                          
459                                                   
460 DRM MM Range Allocator Function References        
461 ------------------------------------------        
462                                                   
463 .. kernel-doc:: include/drm/drm_mm.h              
464    :internal:                                     
465                                                   
466 .. kernel-doc:: drivers/gpu/drm/drm_mm.c          
467    :export:                                       
468                                                   
469 .. _drm_gpuvm:                                    
470                                                   
471 DRM GPUVM                                         
472 =========                                         
473                                                   
474 Overview                                          
475 --------                                          
476                                                   
477 .. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c       
478    :doc: Overview                                 
479                                                   
480 Split and Merge                                   
481 ---------------                                   
482                                                   
483 .. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c       
484    :doc: Split and Merge                          
485                                                   
486 .. _drm_gpuvm_locking:                            
487                                                   
488 Locking                                           
489 -------                                           
490                                                   
491 .. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c       
492    :doc: Locking                                  
493                                                   
494 Examples                                          
495 --------                                          
496                                                   
497 .. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c       
498    :doc: Examples                                 
499                                                   
500 DRM GPUVM Function References                     
501 -----------------------------                     
502                                                   
503 .. kernel-doc:: include/drm/drm_gpuvm.h           
504    :internal:                                     
505                                                   
506 .. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c       
507    :export:                                       
508                                                   
509 DRM Buddy Allocator                               
510 ===================                               
511                                                   
512 DRM Buddy Function References                     
513 -----------------------------                     
514                                                   
515 .. kernel-doc:: drivers/gpu/drm/drm_buddy.c       
516    :export:                                       
517                                                   
518 DRM Cache Handling and Fast WC memcpy()           
519 =======================================           
520                                                   
521 .. kernel-doc:: drivers/gpu/drm/drm_cache.c       
522    :export:                                       
523                                                   
524 .. _drm_sync_objects:                             
525                                                   
526 DRM Sync Objects                                  
527 ================                                  
528                                                   
529 .. kernel-doc:: drivers/gpu/drm/drm_syncobj.c     
530    :doc: Overview                                 
531                                                   
532 .. kernel-doc:: include/drm/drm_syncobj.h         
533    :internal:                                     
534                                                   
535 .. kernel-doc:: drivers/gpu/drm/drm_syncobj.c     
536    :export:                                       
537                                                   
538 DRM Execution context                             
539 =====================                             
540                                                   
541 .. kernel-doc:: drivers/gpu/drm/drm_exec.c        
542    :doc: Overview                                 
543                                                   
544 .. kernel-doc:: include/drm/drm_exec.h            
545    :internal:                                     
546                                                   
547 .. kernel-doc:: drivers/gpu/drm/drm_exec.c        
548    :export:                                       
549                                                   
550 GPU Scheduler                                     
551 =============                                     
552                                                   
553 Overview                                          
554 --------                                          
555                                                   
556 .. kernel-doc:: drivers/gpu/drm/scheduler/sche    
557    :doc: Overview                                 
558                                                   
559 Flow Control                                      
560 ------------                                      
561                                                   
562 .. kernel-doc:: drivers/gpu/drm/scheduler/sche    
563    :doc: Flow Control                             
564                                                   
565 Scheduler Function References                     
566 -----------------------------                     
567                                                   
568 .. kernel-doc:: include/drm/gpu_scheduler.h       
569    :internal:                                     
570                                                   
571 .. kernel-doc:: drivers/gpu/drm/scheduler/sche    
572    :export:                                       
573                                                   
574 .. kernel-doc:: drivers/gpu/drm/scheduler/sche    
575    :export:                                       
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php