forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771 
 kernel/Documentation/gpu/drm-mm.rst
....@@ -72,16 +72,12 @@
7272 the kernel itself. The type of this object should be
7373 TTM_GLOBAL_TTM_BO, and its size should be sizeof(struct
7474 ttm_bo_global). Again, driver-specific init and release functions may
75
-be provided, likely eventually calling ttm_bo_global_init() and
76
-ttm_bo_global_release(), respectively. Also, like the previous
75
+be provided, likely eventually calling ttm_bo_global_ref_init() and
76
+ttm_bo_global_ref_release(), respectively. Also, like the previous
7777 object, ttm_global_item_ref() is used to create an initial reference
7878 count for the TTM, which will call your initialization function.
7979 
8080 See the radeon_ttm.c file for an example of usage.
81
-
82
-.. kernel-doc:: drivers/gpu/drm/drm_global.c
83
-   :export:
84
-
8581 
8682 The Graphics Execution Manager (GEM)
8783 ====================================
....@@ -153,19 +149,19 @@
153149 To create a GEM object, a driver allocates memory for an instance of its
154150 specific GEM object type and initializes the embedded struct
155151 :c:type:`struct drm_gem_object <drm_gem_object>` with a call
156
-to :c:func:`drm_gem_object_init()`. The function takes a pointer
152
+to drm_gem_object_init(). The function takes a pointer
157153 to the DRM device, a pointer to the GEM object and the buffer object
158154 size in bytes.
159155 
160156 GEM uses shmem to allocate anonymous pageable memory.
161
-:c:func:`drm_gem_object_init()` will create an shmfs file of the
157
+drm_gem_object_init() will create an shmfs file of the
162158 requested size and store it into the struct :c:type:`struct
163159 drm_gem_object <drm_gem_object>` filp field. The memory is
164160 used as either main storage for the object when the graphics hardware
165161 uses system memory directly or as a backing store otherwise.
166162 
167163 Drivers are responsible for the actual physical pages allocation by
168
-calling :c:func:`shmem_read_mapping_page_gfp()` for each page.
164
+calling shmem_read_mapping_page_gfp() for each page.
169165 Note that they can decide to allocate pages when initializing the GEM
170166 object, or to delay allocation until the memory is needed (for instance
171167 when a page fault occurs as a result of a userspace memory access or
....@@ -174,21 +170,16 @@
174170 Anonymous pageable memory allocation is not always desired, for instance
175171 when the hardware requires physically contiguous system memory as is
176172 often the case in embedded devices. Drivers can create GEM objects with
177
-no shmfs backing (called private GEM objects) by initializing them with
178
-a call to :c:func:`drm_gem_private_object_init()` instead of
179
-:c:func:`drm_gem_object_init()`. Storage for private GEM objects
180
-must be managed by drivers.
173
+no shmfs backing (called private GEM objects) by initializing them with a call
174
+to drm_gem_private_object_init() instead of drm_gem_object_init(). Storage for
175
+private GEM objects must be managed by drivers.
181176 
182177 GEM Objects Lifetime
183178 --------------------
184179 
185180 All GEM objects are reference-counted by the GEM core. References can be
186
-acquired and release by :c:func:`calling drm_gem_object_get()` and
187
-:c:func:`drm_gem_object_put()` respectively. The caller must hold the
188
-:c:type:`struct drm_device <drm_device>` struct_mutex lock when calling
189
-:c:func:`drm_gem_object_get()`. As a convenience, GEM provides
190
-:c:func:`drm_gem_object_put_unlocked()` functions that can be called without
191
-holding the lock.
181
+acquired and release by calling drm_gem_object_get() and drm_gem_object_put()
182
+respectively.
192183 
193184 When the last reference to a GEM object is released the GEM core calls
194185 the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked
....@@ -198,7 +189,7 @@
198189 void (\*gem_free_object) (struct drm_gem_object \*obj); Drivers are
199190 responsible for freeing all GEM object resources. This includes the
200191 resources created by the GEM core, which need to be released with
201
-:c:func:`drm_gem_object_release()`.
192
+drm_gem_object_release().
202193 
203194 GEM Objects Naming
204195 ------------------
....@@ -214,13 +205,11 @@
214205 DRM file handle frees all its GEM handles and dereferences the
215206 associated GEM objects.
216207 
217
-To create a handle for a GEM object drivers call
218
-:c:func:`drm_gem_handle_create()`. The function takes a pointer
219
-to the DRM file and the GEM object and returns a locally unique handle.
220
-When the handle is no longer needed drivers delete it with a call to
221
-:c:func:`drm_gem_handle_delete()`. Finally the GEM object
222
-associated with a handle can be retrieved by a call to
223
-:c:func:`drm_gem_object_lookup()`.
208
+To create a handle for a GEM object drivers call drm_gem_handle_create(). The
209
+function takes a pointer to the DRM file and the GEM object and returns a
210
+locally unique handle.  When the handle is no longer needed drivers delete it
211
+with a call to drm_gem_handle_delete(). Finally the GEM object associated with a
212
+handle can be retrieved by a call to drm_gem_object_lookup().
224213 
225214 Handles don't take ownership of GEM objects, they only take a reference
226215 to the object that will be dropped when the handle is destroyed. To
....@@ -262,7 +251,7 @@
262251 don't have their own file handle. Two alternative methods currently
263252 co-exist to map GEM objects to userspace. The first method uses a
264253 driver-specific ioctl to perform the mapping operation, calling
265
-:c:func:`do_mmap()` under the hood. This is often considered
254
+do_mmap() under the hood. This is often considered
266255 dubious, seems to be discouraged for new GEM-enabled drivers, and will
267256 thus not be described here.
268257 
....@@ -271,23 +260,22 @@
271260 offset); DRM identifies the GEM object to be mapped by a fake offset
272261 passed through the mmap offset argument. Prior to being mapped, a GEM
273262 object must thus be associated with a fake offset. To do so, drivers
274
-must call :c:func:`drm_gem_create_mmap_offset()` on the object.
263
+must call drm_gem_create_mmap_offset() on the object.
275264 
276265 Once allocated, the fake offset value must be passed to the application
277266 in a driver-specific way and can then be used as the mmap offset
278267 argument.
279268 
280
-The GEM core provides a helper method :c:func:`drm_gem_mmap()` to
269
+The GEM core provides a helper method drm_gem_mmap() to
281270 handle object mapping. The method can be set directly as the mmap file
282271 operation handler. It will look up the GEM object based on the offset
283272 value and set the VMA operations to the :c:type:`struct drm_driver
284
-<drm_driver>` gem_vm_ops field. Note that
285
-:c:func:`drm_gem_mmap()` doesn't map memory to userspace, but
286
-relies on the driver-provided fault handler to map pages individually.
273
+<drm_driver>` gem_vm_ops field. Note that drm_gem_mmap() doesn't map memory to
274
+userspace, but relies on the driver-provided fault handler to map pages
275
+individually.
287276 
288
-To use :c:func:`drm_gem_mmap()`, drivers must fill the struct
289
-:c:type:`struct drm_driver <drm_driver>` gem_vm_ops field
290
-with a pointer to VM operations.
277
+To use drm_gem_mmap(), drivers must fill the struct :c:type:`struct drm_driver
278
+<drm_driver>` gem_vm_ops field with a pointer to VM operations.
291279 
292280 The VM operations is a :c:type:`struct vm_operations_struct <vm_operations_struct>`
293281 made up of several fields, the more interesting ones being:
....@@ -297,14 +285,13 @@
297285 	struct vm_operations_struct {
298286 		void (*open)(struct vm_area_struct * area);
299287 		void (*close)(struct vm_area_struct * area);
300
-		int (*fault)(struct vm_fault *vmf);
288
+		vm_fault_t (*fault)(struct vm_fault *vmf);
301289 	};
302290 
303291 
304292 The open and close operations must update the GEM object reference
305
-count. Drivers can use the :c:func:`drm_gem_vm_open()` and
306
-:c:func:`drm_gem_vm_close()` helper functions directly as open
307
-and close handlers.
293
+count. Drivers can use the drm_gem_vm_open() and drm_gem_vm_close() helper
294
+functions directly as open and close handlers.
308295 
309296 The fault operation handler is responsible for mapping individual pages
310297 to userspace when a page fault occurs. Depending on the memory
....@@ -316,15 +303,15 @@
316303 faults can implement their own mmap file operation handler.
317304 
318305 For platforms without MMU the GEM core provides a helper method
319
-:c:func:`drm_gem_cma_get_unmapped_area`. The mmap() routines will call
320
-this to get a proposed address for the mapping.
306
+drm_gem_cma_get_unmapped_area(). The mmap() routines will call this to get a
307
+proposed address for the mapping.
321308 
322
-To use :c:func:`drm_gem_cma_get_unmapped_area`, drivers must fill the
323
-struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
324
-field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
309
+To use drm_gem_cma_get_unmapped_area(), drivers must fill the struct
310
+:c:type:`struct file_operations <file_operations>` get_unmapped_area field with
311
+a pointer on drm_gem_cma_get_unmapped_area().
325312 
326313 More detailed information about get_unmapped_area can be found in
327
-Documentation/nommu-mmap.txt
314
+Documentation/admin-guide/mm/nommu-mmap.rst
328315 
329316 Memory Coherency
330317 ----------------
....@@ -383,6 +370,39 @@
383370 .. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
384371    :export:
385372 
373
+GEM SHMEM Helper Function Reference
374
+-----------------------------------
375
+
376
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
377
+   :doc: overview
378
+
379
+.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
380
+   :internal:
381
+
382
+.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
383
+   :export:
384
+
385
+GEM VRAM Helper Functions Reference
386
+-----------------------------------
387
+
388
+.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c
389
+   :doc: overview
390
+
391
+.. kernel-doc:: include/drm/drm_gem_vram_helper.h
392
+   :internal:
393
+
394
+.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c
395
+   :export:
396
+
397
+GEM TTM Helper Functions Reference
398
+-----------------------------------
399
+
400
+.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c
401
+   :doc: overview
402
+
403
+.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c
404
+   :export:
405
+
386406 VMA Offset Manager
387407 ==================
388408 
....@@ -404,43 +424,11 @@
404424 created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
405425 buffers are dma-buf based file descriptors.
406426 
407
-Overview and Driver Interface
408
------------------------------
427
+Overview and Lifetime Rules
428
+---------------------------
409429 
410
-Similar to GEM global names, PRIME file descriptors are also used to
411
-share buffer objects across processes. They offer additional security:
412
-as file descriptors must be explicitly sent over UNIX domain sockets to
413
-be shared between applications, they can't be guessed like the globally
414
-unique GEM names.
415
-
416
-Drivers that support the PRIME API must set the DRIVER_PRIME bit in the
417
-struct :c:type:`struct drm_driver <drm_driver>`
418
-driver_features field, and implement the prime_handle_to_fd and
419
-prime_fd_to_handle operations.
420
-
421
-int (\*prime_handle_to_fd)(struct drm_device \*dev, struct drm_file
422
-\*file_priv, uint32_t handle, uint32_t flags, int \*prime_fd); int
423
-(\*prime_fd_to_handle)(struct drm_device \*dev, struct drm_file
424
-\*file_priv, int prime_fd, uint32_t \*handle); Those two operations
425
-convert a handle to a PRIME file descriptor and vice versa. Drivers must
426
-use the kernel dma-buf buffer sharing framework to manage the PRIME file
427
-descriptors. Similar to the mode setting API PRIME is agnostic to the
428
-underlying buffer object manager, as long as handles are 32bit unsigned
429
-integers.
430
-
431
-While non-GEM drivers must implement the operations themselves, GEM
432
-drivers must use the :c:func:`drm_gem_prime_handle_to_fd()` and
433
-:c:func:`drm_gem_prime_fd_to_handle()` helper functions. Those
434
-helpers rely on the driver gem_prime_export and gem_prime_import
435
-operations to create a dma-buf instance from a GEM object (dma-buf
436
-exporter role) and to create a GEM object from a dma-buf instance
437
-(dma-buf importer role).
438
-
439
-struct dma_buf \* (\*gem_prime_export)(struct drm_device \*dev,
440
-struct drm_gem_object \*obj, int flags); struct drm_gem_object \*
441
-(\*gem_prime_import)(struct drm_device \*dev, struct dma_buf
442
-\*dma_buf); These two operations are mandatory for GEM drivers that
443
-support PRIME.
430
+.. kernel-doc:: drivers/gpu/drm/drm_prime.c
431
+   :doc: overview and lifetime rules
444432 
445433 PRIME Helper Functions
446434 ----------------------
....@@ -505,7 +493,7 @@
505493 Overview
506494 --------
507495 
508
-.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c
496
+.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c
509497    :doc: Overview
510498 
511499 Scheduler Function References
....@@ -514,5 +502,5 @@
514502 .. kernel-doc:: include/drm/gpu_scheduler.h
515503    :internal:
516504 
517
-.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c
505
+.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c
518506    :export: