Definition:

struct ttm_global {    struct page *dummy_read_page;    struct list_head device_list;    atomic_t bo_count;};

Members

dummy_read_page

Pointer to a dummy page used for mapping requestsof unpopulated pages. Constant after init.

device_list

List of buffer object devices. Protected byttm_global_mutex.

bo_count

Number of buffer objects allocated by devices.

Definition:

struct ttm_device {    struct list_head device_list;    unsigned int alloc_flags;    const struct ttm_device_funcs *funcs;    struct ttm_resource_manager sysman;    struct ttm_resource_manager *man_drv[TTM_NUM_MEM_TYPES];    struct drm_vma_offset_manager *vma_manager;    struct ttm_pool pool;    spinlock_t lru_lock;    struct list_head unevictable;    struct address_space *dev_mapping;    struct workqueue_struct *wq;};

Members

device_list

Our entry in the global device list.Constant after bo device init

alloc_flags

TTM_ALLOCATION_* flags.

funcs

Function table for the device.Constant after bo device init

sysman

Resource manager for the system domain.Access via ttm_manager_type.

man_drv

An array of resource_managers, one per resource type.

vma_manager

Address space manager for finding BOs to mmap.

pool

page pool for the device.

lru_lock

Protection for the per manager LRU and ddestroy lists.

unevictable

Buffer objects which are pinned or swapped and as suchnot on an LRU list.

dev_mapping

A pointer to thestructaddress_space for invalidatingCPU mappings on buffer move. Protected by load/unload sync.

wq

Work queue structure for the delayed delete workqueue.

Parameters

structttm_device*bdev

A pointer to astructttm_device to prepare hibernation for.

Return

0 on success, negative number on failure.

Parameters

structttm_device*bdev

A pointer to astructttm_device to initialize.

conststructttm_device_funcs*funcs

Function table for the device.

structdevice*dev

The core kernel device pointer for DMA mappings and allocations.

structaddress_space*mapping

The address space to use for this bo.

structdrm_vma_offset_manager*vma_manager

A pointer to a vma manager.

unsignedintalloc_flags

TTM_ALLOCATION_* flags.

Description

Initializes astructttm_device:

Return

!0: Failure.

Definition:

struct ttm_place {    unsigned fpfn;    unsigned lpfn;    uint32_t mem_type;    uint32_t flags;};

Members

fpfn

first valid page frame number to put the object

lpfn

last valid page frame number to put the object

mem_type

One of TTM_PL_* where the resource should be allocated from.

flags

memory domain and caching flags for the object

Definition:

struct ttm_placement {    unsigned num_placement;    const struct ttm_place  *placement;};

Members

num_placement

number of preferred placements

placement

preferred placements

Constants

TTM_LRU_RESOURCE

The resource subclass

TTM_LRU_HITCH

The iterator hitch subclass

Definition:

struct ttm_lru_item {    struct list_head link;    enum ttm_lru_item_type type;};

Members

link

The list link

type

The subclass type

Parameters

structttm_lru_item*item

The item to initialize

enumttm_lru_item_typetype

The subclass type

Definition:

struct ttm_resource_manager {    bool use_type;    bool use_tt;    struct ttm_device *bdev;    uint64_t size;    const struct ttm_resource_manager_func *func;    spinlock_t eviction_lock;    struct dma_fence *eviction_fences[TTM_NUM_MOVE_FENCES];    struct list_head lru[TTM_MAX_BO_PRIORITY];    uint64_t usage;    struct dmem_cgroup_region *cg;};

Members

use_type

The memory type is enabled.

use_tt

If a TT object should be used for the backing store.

bdev

ttm device this manager belongs to

size

Size of the managed region.

func

structure pointer implementing the range manager. See above

eviction_lock

lock for eviction fences

eviction_fences

The fences of the last pipelined move operation.

lru

The lru list for this memory type.

usage

How much of the resources are used, protected by thebdev->lru_lock.

cg

dmem_cgroup_region used for memory accounting, if not NULL.

Definition:

struct ttm_bus_placement {    void *addr;    phys_addr_t offset;    bool is_iomem;    enum ttm_caching        caching;};

Members

addr

mapped virtual address

offset

physical addr

is_iomem

is this io memory ?

caching

Seeenumttm_caching

Definition:

struct ttm_resource {    unsigned long start;    size_t size;    uint32_t mem_type;    uint32_t placement;    struct ttm_bus_placement bus;    struct ttm_buffer_object *bo;    struct dmem_cgroup_pool_state *css;    struct ttm_lru_item lru;};

Members

start

Start of the allocation.

size

Actual size of resource in bytes.

mem_type

Resource type of the allocation.

placement

Placement flags.

bus

Placement on io bus accessible to the CPU

bo

weak reference to the BO, protected by ttm_device::lru_lock

css

cgroup state this resource is charged to

lru

Least recently used list, seettm_resource_manager.lru

Parameters

structttm_lru_item*item

Thestructttm_lru_item to downcast

Return

Pointer to the embeddingstructttm_resource

Definition:

struct ttm_lru_bulk_move_pos {    struct ttm_resource *first;    struct ttm_resource *last;};

Members

first

first res in the bulk move range

last

last res in the bulk move range

Definition:

struct ttm_lru_bulk_move {    struct ttm_lru_bulk_move_pos pos[TTM_NUM_MEM_TYPES][TTM_MAX_BO_PRIORITY];    struct list_head cursor_list;};

Members

pos

first/last lru entry for resources in the each domain/priority

cursor_list

The list of cursors currently traversing any ofthe sublists ofpos. Protected by the ttm device’s lru_lock.

Definition:

struct ttm_resource_cursor {    struct ttm_resource_manager *man;    struct ttm_lru_item hitch;    struct list_head bulk_link;    struct ttm_lru_bulk_move *bulk;    unsigned int mem_type;    unsigned int priority;};

Members

man

The resource manager currently being iterated over

hitch

A hitch list node inserted before the next resourceto iterate over.

bulk_link

A list link for the list of cursors traversing thebulk sublist ofbulk. Protected by the ttm device’s lru_lock.

bulk

Pointer tostructttm_lru_bulk_move whose subrangehitch isinserted to. NULL if none. Never dereference this pointer sincethestructttm_lru_bulk_move object pointed to might have beenfreed. The pointer is only for comparison.

mem_type

The memory type of the LRU list being traversed.This field is valid iffbulk != NULL.

priority

the current priority

Definition:

struct ttm_kmap_iter_iomap {    struct ttm_kmap_iter base;    struct io_mapping *iomap;    struct sg_table *st;    resource_size_t start;    struct {        struct scatterlist *sg;        pgoff_t i;        pgoff_t end;        pgoff_t offs;    } cache;};

Members

base

Embeddedstructttm_kmap_iter providing the usage interface.

iomap

structio_mapping representing the underlying linear io_memory.

st

sg_table intoiomap, representing the memory of thestructttm_resource.

start

Offset that needs to be subtracted fromst to makesg_dma_address(st->sgl) -start == 0 foriomap start.

cache

Scatterlist traversal cache for fast lookups.

cache.sg

Pointer to the currently cached scatterlist segment.

cache.i

First index ofsg. PAGE_SIZE granularity.

cache.end

Last index + 1 ofsg. PAGE_SIZE granularity.

cache.offs

First offset intoiomap ofsg. PAGE_SIZE granularity.

Definition:

struct ttm_kmap_iter_linear_io {    struct ttm_kmap_iter base;    struct iosys_map dmap;    bool needs_unmap;};

Members

base

The base iterator

dmap

Points to the starting address of the region

needs_unmap

Whether we need to unmap on fini

Parameters

structttm_resource_manager*man

A memory manager object.

boolused

usage state to set.

Description

Set the manager in use flag. If disabled the manager is no longerused for object placement.

Parameters

structttm_resource_manager*man

Manager to get used state for

Description

Get the in use flag for a manager.

Return

true is used, false if not.

Parameters

structttm_resource_manager*man

A memory manager object.

Description

Cleanup the move fences from the memory manager object.

Parameters

cursor

structttm_resource_cursor for the current position

res

the current resource

Description

Iterate over all the evictable resources in a resource manager.

Parameters

structttm_lru_bulk_move*bulk

the structure to init

Description

For now just memset the structure to zero.

Parameters

structttm_device*bdev

Thestructttm_device

structttm_lru_bulk_move*bulk

the structure to finalize

Description

Sanity checks that bulk moves don’t have anyresources left and hence no cursors attached.

Parameters

structttm_lru_bulk_move*bulk

bulk move structure

Description

Bulk move BOs to the LRU tail, only valid to use when driver makes sure thatresource order never changes. Should be called withttm_device.lru_lock held.

Parameters

structttm_buffer_object*bo

buffer object this resources is allocated for

conststructttm_place*place

placement of the resource

structttm_resource*res

the resource object to inistilize

Description

Initialize a new resource object. Counterpart ofttm_resource_fini().

Parameters

structttm_resource_manager*man

the resource manager this resource belongs to

structttm_resource*res

the resource to clean up

Description

Should be used by resource manager backends to clean up the TTM resourceobjects before freeing the underlying structure. Makes sure the resource isremoved from the LRU before destruction.Counterpart ofttm_resource_init().

Parameters

structttm_resource_manager*man

memory manager object to init

structttm_device*bdev

ttm device this manager belongs to

uint64_tsize

size of managed resources in arbitrary units

Description

Initialise core parts of a manager object.

Parameters

structttm_resource_manager*man

A memory manager object.

Description

Return how many resources are currently used.

Parameters

structttm_resource_manager*man

manager type to dump.

structdrm_printer*p

printer to use for debug.

Parameters

structttm_kmap_iter_iomap*iter_io

Thestructttm_kmap_iter_iomap to initialize.

structio_mapping*iomap

Thestructio_mapping representing the underlying linear io_memory.

structsg_table*st

sg_table intoiomap, representing the memory of thestructttm_resource.

resource_size_tstart

Offset that needs to be subtracted fromst to makesg_dma_address(st->sgl) -start == 0 foriomap start.

Return

Pointer to the embeddedstructttm_kmap_iter.

Parameters

structttm_resource_manager*man

The TTM resource manager for which the debugfs stats file be creates

structdentry*parent

debugfs directory in which the file will reside

constchar*name

The filename to create.

Description

This function setups up a debugfs file that can be used to lookat debug statistics of the specified ttm_resource_manager.

Definition:

struct ttm_tt {    struct page **pages;#define TTM_TT_FLAG_SWAPPED             BIT(0);#define TTM_TT_FLAG_ZERO_ALLOC          BIT(1);#define TTM_TT_FLAG_EXTERNAL            BIT(2);#define TTM_TT_FLAG_EXTERNAL_MAPPABLE   BIT(3);#define TTM_TT_FLAG_DECRYPTED           BIT(4);#define TTM_TT_FLAG_BACKED_UP           BIT(5);#define TTM_TT_FLAG_PRIV_POPULATED      BIT(6);    uint32_t page_flags;    uint32_t num_pages;    struct sg_table *sg;    dma_addr_t *dma_address;    struct file *swap_storage;    struct file *backup;    enum ttm_caching caching;    struct ttm_pool_tt_restore *restore;};

Members

pages

Array of pages backing the data.

page_flags

The page flags.

Supported values:

TTM_TT_FLAG_SWAPPED: Set by TTM when the pages have been unpopulatedand swapped out by TTM. Callingttm_tt_populate() will then swap thepages back in, and unset the flag. Drivers should in general neverneed to touch this.

TTM_TT_FLAG_ZERO_ALLOC: Set if the pages will be zeroed onallocation.

TTM_TT_FLAG_EXTERNAL: Set if the underlying pages were allocatedexternally, like with dma-buf or userptr. This effectively disablesTTM swapping out such pages. Also important is to prevent TTM fromever directly mapping these pages.

Note thatenumttm_bo_type.ttm_bo_type_sg objects will always enablethis flag.

TTM_TT_FLAG_EXTERNAL_MAPPABLE: Same behaviour asTTM_TT_FLAG_EXTERNAL, but with the reduced restriction that it isstill valid to use TTM to map the pages directly. This is useful whenimplementing a ttm_tt backend which still allocates driver ownedpages underneath(say with shmem).

Note that since this also implies TTM_TT_FLAG_EXTERNAL, the usagehere should always be:

page_flags = TTM_TT_FLAG_EXTERNAL |

TTM_TT_FLAG_EXTERNAL_MAPPABLE;

TTM_TT_FLAG_DECRYPTED: The mapped ttm pages should be marked asnot encrypted. The framework will try to match what the dma layeris doing, but note that it is a little fragile because ttm pagefault handling abuses the DMA api a bit and dma_map_attrs can’t beused to assure pgprot always matches.

TTM_TT_FLAG_BACKED_UP: TTM internal only. This is set if thestructttm_tt has been (possibly partially) backed up.

TTM_TT_FLAG_PRIV_POPULATED: TTM internal only. DO NOT USE. This isset by TTM afterttm_tt_populate() has successfully returned, and isthen unset when TTM callsttm_tt_unpopulate().

num_pages

Number of pages in the page array.

sg

for SG objects via dma-buf.

dma_address

The DMA (bus) addresses of the pages.

swap_storage

Pointer to shmemstructfile for swap storage.

backup

Pointer to backup struct for backed up tts.Could be unified withswap_storage. Meanwhile, the driver’sttm_tt_create() callback is responsible for assigningthis field.

caching

The current caching state of the pages, seeenumttm_caching.

restore

Partial restoration from backup state. TTM private

Definition:

struct ttm_kmap_iter_tt {    struct ttm_kmap_iter base;    struct ttm_tt *tt;    pgprot_t prot;};

Members

base

Embeddedstructttm_kmap_iter providing the usage interface

tt

Cachedstructttm_tt.

prot

Cached page protection for mapping.

Parameters

conststructttm_tt*tt

Thestructttm_tt.

Return

true if swapped or backed up, false otherwise.

Parameters

conststructttm_tt*tt

Thestructttm_tt.

Return

true if swapped or backed up, false otherwise.

Parameters

structttm_tt*tt

Thestructttm_tt.

Description

Drivers can use this functionto clear the backed-up status,for example before destroying or re-validating a purged tt.

Parameters

structttm_buffer_object*bo

pointer to astructttm_buffer_object

boolzero_alloc

true if allocated pages needs to be zeroed

Description

Make sure we have a TTM structure allocated for the given BO.No pages are actually allocated.

Parameters

structttm_tt*ttm

Thestructttm_tt.

structttm_buffer_object*bo

The buffer object we create the ttm for.

uint32_tpage_flags

Page flags as identified by TTM_TT_FLAG_XX flags.

enumttm_cachingcaching

the desired caching state of the pages

unsignedlongextra_pages

Extra pages needed for the driver.

Description

Create astructttm_tt to back data with system memory pages.No pages are actually allocated.

Return

NULL: Out of memory.

Parameters

structttm_tt*ttm

the ttm_tt structure.

Description

Free memory of ttm_tt structure

Parameters

structttm_device*bdev

the ttm_device this object belongs to

structttm_tt*ttm

Thestructttm_tt.

Description

Unbind, unpopulate and destroy commonstructttm_tt.

Parameters

structttm_tt*ttm

Thestructttm_tt.

Description

Swap in a previously swap out ttm_tt.

Parameters

structttm_device*bdev

the ttm_device this object belongs to

structttm_tt*ttm

Pointer to the ttm_tt structure

structttm_operation_ctx*ctx

operation context for populating the tt object.

Description

Calls the driver method to allocate pages for a ttm

Parameters

structttm_device*bdev

the ttm_device this object belongs to

structttm_tt*ttm

Pointer to the ttm_tt structure

Description

Calls the driver method to free all pages from a ttm

Parameters

structttm_tt*ttm

Pointer to the ttm_tt structure

Description

Marks pages for clearing so that the next time the page vector ispopulated, the pages will be cleared.

Definition:

struct ttm_backup_flags {    u32 purge : 1;    u32 writeback : 1;};

Members

purge

Free pages without backing up. Bypass pools.

writeback

Attempt to copy contents directly to swap space, evenif that means blocking on writes to external memory.

Parameters

structttm_buffer_object*bo

Buffer object we allocate the ttm for.

structagp_bridge_data*bridge

The agp bridge this device is sitting on.

uint32_tpage_flags

Page flags as identified by TTM_TT_FLAG_XX flags.

Description

Create a TTM backend that uses the indicated AGP bridge as an aperturefor TT memory. This function uses the linux agpgart interface tobind and unbind memory backing a ttm_tt.

Parameters

structttm_kmap_iter_tt*iter_tt

Thestructttm_kmap_iter_tt to initialize.

structttm_tt*tt

Struct ttm_tt holding page pointers of thestructttm_resource.

Return

Pointer to the embeddedstructttm_kmap_iter.

Parameters

structttm_tt*tt

The ttm_tt for wich to allocate and assign a backup structure.

Description

Assign a backup structure to be used for tt backup. This shouldtypically be done at bo creation, to avoid allocations at shrinkingtime.

Return

0 on success, negative error code on failure.

Definition:

struct ttm_pool_type {    struct ttm_pool *pool;    unsigned int order;    enum ttm_caching caching;    struct list_head shrinker_list;    spinlock_t lock;    struct list_head pages;};

Members

pool

the pool we belong to, might be NULL for the global ones

order

the allocation order our pages have

caching

the caching type our pages have

shrinker_list

our place on the global shrinker list

lock

protection of the page list

pages

the list of pages in the pool

Definition:

struct ttm_pool {    struct device *dev;    int nid;    unsigned int alloc_flags;    struct {        struct ttm_pool_type orders[NR_PAGE_ORDERS];    } caching[TTM_NUM_CACHING_TYPES];};

Members

dev

the device we allocate pages for

nid

which numa node to use

alloc_flags

TTM_ALLOCATION_POOL_* flags

caching

pools for each caching/order

Parameters

structttm_pool*pool

ttm_pool to use

structttm_tt*tt

ttm_tt object to fill

structttm_operation_ctx*ctx

operation context

Description

Fill the ttm_tt object with pages and also make sure to DMA map them whennecessary.

Return

0 on successe, negative error code otherwise.

Parameters

structttm_pool*pool

Pool to give pages back to.

structttm_tt*tt

ttm_tt object to unpopulate

Description

Give the packing pages back to a pool or free them

Parameters

structttm_pool*pool

the pool to initialize

structdevice*dev

device for DMA allocations and mappings

intnid

NUMA node to use for allocations

unsignedintalloc_flags

TTM_ALLOCATION_POOL_* flags

Description

Initialize the pool and its pool types.

Parameters

structttm_pool*pool

the pool to clean up

Description

Free all pages in the pool and unregister the types from the globalshrinker.

Parameters

structttm_pool*pool

the pool to dump the information for

structseq_file*m

seq_file to dump to

Description

Make a debugfs dump with the per pool and global information.

Constants

DRM_GEM_OBJECT_RESIDENT

object is resident in memory (ie. not unpinned)

DRM_GEM_OBJECT_PURGEABLE

object marked as purgeable by userspace

DRM_GEM_OBJECT_ACTIVE

object is currently used by an active submission

Definition:

struct drm_gem_object_funcs {    void (*free)(struct drm_gem_object *obj);    int (*open)(struct drm_gem_object *obj, struct drm_file *file);    void (*close)(struct drm_gem_object *obj, struct drm_file *file);    void (*print_info)(struct drm_printer *p, unsigned int indent, const struct drm_gem_object *obj);    struct dma_buf *(*export)(struct drm_gem_object *obj, int flags);    int (*pin)(struct drm_gem_object *obj);    void (*unpin)(struct drm_gem_object *obj);    struct sg_table *(*get_sg_table)(struct drm_gem_object *obj);    int (*vmap)(struct drm_gem_object *obj, struct iosys_map *map);    void (*vunmap)(struct drm_gem_object *obj, struct iosys_map *map);    int (*mmap)(struct drm_gem_object *obj, struct vm_area_struct *vma);    int (*evict)(struct drm_gem_object *obj);    enum drm_gem_object_status (*status)(struct drm_gem_object *obj);    size_t (*rss)(struct drm_gem_object *obj);    const struct vm_operations_struct *vm_ops;};

Members

free

Deconstructor for drm_gem_objects.

This callback is mandatory.

open

Called upon GEM handle creation.

This callback is optional.

close

Called upon GEM handle release.

This callback is optional.

print_info

If driver subclasses structdrm_gem_object, it can implement thisoptional hook for printing additional driver specific info.

drm_printf_indent() should be used in the callback passing it theindent argument.

This callback is called fromdrm_gem_print_info().

This callback is optional.

export

Export backing buffer as adma_buf.If this is not setdrm_gem_prime_export() is used.

This callback is optional.

pin

Pin backing buffer in memory, such that dma-buf importers canaccess it. Used by thedrm_gem_map_attach() helper.

This callback is optional.

unpin

Unpin backing buffer. Used by thedrm_gem_map_detach() helper.

This callback is optional.

get_sg_table

Returns a Scatter-Gather table representation of the buffer.Used when exporting a buffer by thedrm_gem_map_dma_buf() helper.Releasing is done by callingdma_unmap_sg_attrs() andsg_free_table()indrm_gem_unmap_buf(), therefore these helpers and this callbackhere cannot be used for sg tables pointing at driver private memoryranges.

See alsodrm_prime_pages_to_sg().

vmap

Returns a virtual address for the buffer. Used by thedrm_gem_dmabuf_vmap() helper. Called with a held GEM reservationlock.

This callback is optional.

vunmap

Releases the address previously returned byvmap. Used by thedrm_gem_dmabuf_vunmap() helper. Called with a held GEM reservationlock.

This callback is optional.

mmap

Handle mmap() of the gem object, setup vma accordingly.

This callback is optional.

The callback is used by bothdrm_gem_mmap_obj() anddrm_gem_prime_mmap(). Whenmmap is presentvm_ops is notused, themmap callback must set vma->vm_ops instead.

evict

Evicts gem object out from memory. Used by thedrm_gem_object_evict()helper. Returns 0 on success, -errno otherwise. Called with a heldGEM reservation lock.

This callback is optional.

status

The optional status callback can return additional object statewhich determines which stats the object is counted against. Thecallback is called under table_lock. Racing against object statuschange is “harmless”, and the callback can expect to not raceagainst object destruction.

Called bydrm_show_memory_stats().

rss

Return resident size of the object in physical memory.

Called bydrm_show_memory_stats().

vm_ops

Virtual memory operations used with mmap.

This is optional but necessary for mmap support.

Definition:

struct drm_gem_lru {    struct mutex *lock;    long count;    struct list_head list;};

Members

lock

Lock protecting movement of GEM objects between LRUs. AllLRUs that the object can move between should be protectedby the same lock.

count

The total number of backing pages of the GEM objects inthis LRU.

list

The LRU list.

Definition:

struct drm_gem_object {    struct kref refcount;    unsigned handle_count;    struct drm_device *dev;    struct file *filp;    struct drm_vma_offset_node vma_node;    size_t size;    int name;    struct dma_buf *dma_buf;    struct dma_buf_attachment *import_attach;    struct dma_resv *resv;    struct dma_resv _resv;    struct {        struct list_head list;        struct mutex lock;    } gpuva;    const struct drm_gem_object_funcs *funcs;    struct list_head lru_node;    struct drm_gem_lru *lru;};

Members

refcount

Reference count of this object

Please usedrm_gem_object_get() to acquire anddrm_gem_object_put_locked()ordrm_gem_object_put() to release a reference to a GEMbuffer object.

handle_count

This is the GEM file_priv handle count of this object.

Each handle also holds a reference. Note that when the handle_countdrops to 0 any global names (e.g. the id in the flink namespace) willbe cleared.

Protected bydrm_device.object_name_lock.

dev

DRM dev this object belongs to.

filp

SHMEM file node used as backing storage for swappable buffer objects.GEM also supports driver private objects with driver-specific backingstorage (contiguous DMA memory, special reserved blocks). In thiscasefilp is NULL.

vma_node

Mapping info for this object to support mmap. Drivers are supposed toallocate the mmap offset usingdrm_gem_create_mmap_offset(). Theoffset itself can be retrieved usingdrm_vma_node_offset_addr().

Memory mapping itself is handled bydrm_gem_mmap(), which also checksthat userspace is allowed to access the object.

size

Size of the object, in bytes. Immutable over the object’slifetime.

name

Global name for this object, starts at 1. 0 means unnamed.Access is covered bydrm_device.object_name_lock. This is used bythe GEM_FLINK and GEM_OPEN ioctls.

dma_buf

dma-buf associated with this GEM object.

Pointer to the dma-buf associated with this gem object (eitherthrough importing or exporting). We break the resulting referenceloop when the last gem handle for this object is released.

Protected bydrm_device.object_name_lock.

import_attach

dma-buf attachment backing this object.

Any foreign dma_buf imported as a gem object has this set to theattachment point for the device. This is invariant over the lifetimeof a gem object.

Thedrm_gem_object_funcs.free callback is responsible forcleaning up the dma_buf attachment and references acquired at importtime.

Note that the drm gem/prime core does not depend upon drivers settingthis field any more. So for drivers where this doesn’t make sense(e.g. virtual devices or a displaylink behind an usb bus) they cansimply leave it as NULL.

resv

Pointer to reservation object associated with the this GEM object.

Normally (resv == &**_resv**) except for imported GEM objects.

_resv

A reservation object for this GEM object.

This is unused for imported GEM objects.

gpuva

Fields used by GPUVM to manage mappings pointing to this GEM object.

When DRM_GPUVM_IMMEDIATE_MODE is set, this list is protected by themutex. Otherwise, the list is protected by the GEMsdma_resv lock.

Note that all entries in this list must agree on whetherDRM_GPUVM_IMMEDIATE_MODE is set.

gpuva.list

list of GPUVM mappings attached to this GEM object.

Drivers should lock list accesses with either the GEMsdma_resv lock (drm_gem_object.resv) or thedrm_gem_object.gpuva.lock mutex.

gpuva.lock

lock protecting access todrm_gem_object.gpuva.listwhen DRM_GPUVM_IMMEDIATE_MODE is used.

Only used when DRM_GPUVM_IMMEDIATE_MODE is set. It should besafe to take this mutex during the fence signalling path, sodo not allocate memory while holding this lock. Otherwise,thedma_resv lock should be used.

funcs

Optional GEM object functions. If this is set, it will be used instead of thecorrespondingdrm_driver GEM callbacks.

New drivers should use this.

lru_node

List node in adrm_gem_lru.

lru

The current LRU list that the GEM object is on.

Parameters

name

name for the generated structure

Description

This macro autogenerates a suitablestructfile_operations for GEM baseddrivers, which can be assigned todrm_driver.fops. Note that this structurecannot be shared between drivers, because it contains a reference to thecurrent module using THIS_MODULE.

Note that the declaration is already marked as static - if you need anon-static version of this you’re probably doing it wrong and will break theTHIS_MODULE reference by accident.

Parameters

structdrm_device*dev

DRM device

Description

This function gets the huge tmpfs mountpoint used by DRM devicedev. A hugetmpfs mountpoint is used instead ofshm_mnt after a successful call todrm_gem_huge_mnt_create() when CONFIG_TRANSPARENT_HUGEPAGE is enabled.

Return

The huge tmpfs mountpoint in use, NULL otherwise.

Parameters

structdrm_gem_object*obj

GEM buffer object

Description

This function acquires an additional reference toobj. It is illegal tocall this without already holding a reference. No locks required.

Parameters

structdrm_gem_object*obj

GEM buffer object

Description

This releases a reference toobj.

Parameters

structdrm_gem_object*obj

obj in question

Description

This helper should only be used for fdinfo shared memory stats to determineif a GEM object is shared.

Parameters

conststructdrm_gem_object*obj

the GEM object

Return

True if the GEM object’s buffer has been imported, false otherwise

Parameters

structdrm_gem_object*obj

thedrm_gem_object

Description

This initializes thedrm_gem_object’sdrm_gpuvm_bo list.

Calling this function is only necessary for drivers intending to support thedrm_driver_feature DRIVER_GEM_GPUVA.

See alsodrm_gem_gpuva_set_lock().

Parameters

entry__

drm_gpuvm_bo structure to assign to in each iteration step

obj__

thedrm_gem_object thedrm_gpuvm_bo to walk are associated with

Description

This iterator walks over alldrm_gpuvm_bo structures associated with thedrm_gem_object.

Parameters

entry__

drm_gpuvm_bostructure to assign to in each iteration step

next__

nextdrm_gpuvm_bo to store the next step

obj__

thedrm_gem_object thedrm_gpuvm_bo to walk are associated with

Description

This iterator walks over alldrm_gpuvm_bo structures associated with thedrm_gem_object. It is implemented withlist_for_each_entry_safe(), henceit is save against removal of elements.

Parameters

structdrm_device*dev

DRM device that will use the huge tmpfs mountpoint

constchar*value

huge tmpfs mount option value

Description

This function creates and mounts a dedicated huge tmpfs mountpoint for thelifetime of the DRM devicedev which is used at GEM object initializationwithdrm_gem_object_init().

The most common option forvalue is “within_size” which only allocates hugepages if the page will be fully within the GEM object size. “always”,“advise” and “never” are supported too but the latter would just create amountpoint similar to the default one (shm_mnt). See shmemfs andTransparent Hugepage for more information.

Return

0 on success or a negative error code on failure.

Parameters

structdrm_device*dev

drm_device the object should be initialized for

structdrm_gem_object*obj

drm_gem_object to initialize

size_tsize

object size

Description

Initialize an already allocated GEM object of the specified size withshmfs backing store. A huge mountpoint can be used by callingdrm_gem_huge_mnt_create() beforehand.

Parameters

structdrm_device*dev

drm_device the object should be initialized for

structdrm_gem_object*obj

drm_gem_object to initialize

size_tsize

object size

Description

Initialize an already allocated GEM object of the specified size withno GEM provided backing store. Instead the caller is responsible forbacking the object and handling it.

Parameters

structdrm_gem_object*obj

drm_gem_object

Description

Uninitialize an already allocated GEM object when it initialized failed

Parameters

structdrm_file*filp

drm file-private structure to use for the handle look up

u32handle

userspace handle to delete

Description

Removes the GEM handle from thefilp lookup table which has been added withdrm_gem_handle_create(). If this is the last handle also cleans up linkedresources like GEM names.

Parameters

structdrm_file*file

drm file-private structure containing the gem object

structdrm_device*dev

corresponding drm_device

u32handle

gem object handle

u64*offset

return location for the fake mmap offset

Description

This implements thedrm_driver.dumb_map_offset kms driver callback fordrivers which use gem to manage their backing storage.

Return

0 on success or a negative error code on failure.

Parameters

structdrm_file*file_priv

drm file-private structure to register the handle for

structdrm_gem_object*obj

object to register

u32*handlep

pointer to return the created handle to the caller

Description

Create a handle for this object. This adds a handle reference to the object,which includes a regular reference count. Callers will likely want todereference the object afterwards.

Since this publishesobj to userspace it must be fully set up by this point,drivers must call this last in their buffer object creation callbacks.

Parameters

structdrm_gem_object*obj

obj in question

Description

This routine frees fake offsets allocated bydrm_gem_create_mmap_offset().

Note thatdrm_gem_object_release() already calls this function, so driversdon’t have to take care of releasing the mmap offset themselves when freeingthe GEM object.

Parameters

structdrm_gem_object*obj

obj in question

size_tsize

the virtual size

Description

GEM memory mapping works by handing back to userspace a fake mmap offsetit can use in a subsequent mmap(2) call. The DRM core code then looksup the object based on the offset and sets up the various memory mappingstructures.

This routine allocates and attaches a fake offset forobj, in cases wherethe virtual size differs from the physical size (ie.drm_gem_object.size).Otherwise just usedrm_gem_create_mmap_offset().

This function is idempotent and handles an already allocated mmap offsettransparently. Drivers do not need to check for this case.

Parameters

structdrm_gem_object*obj

obj in question

Description

GEM memory mapping works by handing back to userspace a fake mmap offsetit can use in a subsequent mmap(2) call. The DRM core code then looksup the object based on the offset and sets up the various memory mappingstructures.

This routine allocates and attaches a fake offset forobj.

Drivers can calldrm_gem_free_mmap_offset() before freeingobj to releasethe fake offset again.

Parameters

structdrm_gem_object*obj

obj in question

Description

This reads the page-array of the shmem-backing storage of the given gemobject. An array of pages is returned. If a page is not allocated orswapped-out, this will allocate/swap-in the required pages. Note that thewhole object is covered by the page-array and pinned in memory.

Usedrm_gem_put_pages() to release the array and unpin all pages.

This uses the GFP-mask set on the shmem-mapping (seemapping_set_gfp_mask()).If you require other GFP-masks, you have to do those allocations yourself.

Note that you are not allowed to change gfp-zones during runtime. That is,shmem_read_mapping_page_gfp() must be called with the same gfp_zone(gfp) asset during initialization. If you have special zone constraints, set themafterdrm_gem_object_init() viamapping_set_gfp_mask(). shmem-core takes careto keep pages in the required zone during swap-in.

This function is only valid on objects initialized withdrm_gem_object_init(), but not for those initialized withdrm_gem_private_object_init() only.

Parameters

structdrm_gem_object*obj

obj in question

structpage**pages

pages to free

booldirty

if true, pages will be marked as dirty

boolaccessed

if true, the pages will be marked as accessed

Parameters

structdrm_file*filp

DRM file private date

void__user*bo_handles

user pointer to array of userspace handle

intcount

size of handle array

structdrm_gem_object***objs_out

returned pointer to array of drm_gem_object pointers

Description

Takes an array of userspace handles and returns a newly allocated array ofGEM objects.

For a single handle lookup, usedrm_gem_object_lookup().

Return

objs filled in with GEM object pointers. Returned GEM objects need to bereleased withdrm_gem_object_put(). -ENOENT is returned on a lookupfailure. 0 is returned on success.

Parameters

structdrm_file*filp

DRM file private date

u32handle

userspace handle

Description

If looking up an array of handles, usedrm_gem_objects_lookup().

Return

A reference to the object named by the handle if such exists onfilp, NULLotherwise.

Parameters

structdrm_file*filep

DRM file private date

u32handle

userspace handle

boolwait_all

if true, wait on all fences, else wait on just exclusive fence

unsignedlongtimeout

timeout value in jiffies or zero to return immediately

Return

Returns -ERESTARTSYS if interrupted, 0 if the wait timed out, orgreater than 0 on success.

Parameters

structdrm_gem_object*obj

GEM buffer object

Description

This releases any structures and resources used byobj and is the inverse ofdrm_gem_object_init().

Parameters

structkref*kref

kref of the object to free

Description

Called after the last reference to the object has been lost.

Frees the object

Parameters

structvm_area_struct*vma

VM area structure

Description

This function implements the #vm_operations_struct open() callback for GEMdrivers. This must be used together withdrm_gem_vm_close().

Parameters

structvm_area_struct*vma

VM area structure

Description

This function implements the #vm_operations_struct close() callback for GEMdrivers. This must be used together withdrm_gem_vm_open().

Parameters

structdrm_gem_object*obj

the GEM object to map

unsignedlongobj_size

the object size to be mapped, in bytes

structvm_area_struct*vma

VMA for the area to be mapped

Description

Set up the VMA to prepare mapping of the GEM object using the GEM object’svm_ops. Depending on their requirements, GEM objects can eitherprovide a fault handler in their vm_ops (in which case any accesses tothe object will be trapped, to perform migration, GTT binding, surfaceregister allocation, or performance monitoring), or mmap the buffer memorysynchronously after calling drm_gem_mmap_obj.

This function is mainly intended to implement the DMABUF mmap operation, whenthe GEM object is not looked up based on its fake offset. To implement theDRM mmap operation, drivers should use thedrm_gem_mmap() function.

drm_gem_mmap_obj() assumes the user is granted access to the buffer whiledrm_gem_mmap() prevents unprivileged users from mapping random objects. Socallers must verify access restrictions before calling this helper.

Return 0 or success or -EINVAL if the object size is smaller than the VMAsize, or if no vm_ops are provided.

Parameters

structfile*filp

DRM file pointer

unsignedlonguaddr

User address hint

unsignedlonglen

Mapping length

unsignedlongpgoff

Offset (in pages)

unsignedlongflags

Mapping flags

Description

If a driver supports GEM object mapping, before ending up indrm_gem_mmap(),mmap calls on the DRM file descriptor will first try to find a free linearaddress space large enough for a mapping. Since GEM objects are backed byshmem buffers, this should preferably be handled by the shmem virtual memoryfilesystem which can appropriately align addresses to huge page sizes whenneeded.

Look up the GEM object based on the offset passed in (vma->vm_pgoff willcontain the fake offset we created) and callshmem_get_unmapped_area() withthe right file pointer.

If a GEM object is not available at the given offset or if the caller is notgranted access to it, fall back tomm_get_unmapped_area().

Parameters

structfile*filp

DRM file pointer

structvm_area_struct*vma

VMA for the area to be mapped

Description

If a driver supports GEM object mapping, mmap calls on the DRM filedescriptor will end up here.

Look up the GEM object based on the offset passed in (vma->vm_pgoff willcontain the fake offset we created) and map it with a call todrm_gem_mmap_obj().

If the caller is not granted access to the buffer object, the mmap will failwith EACCES. Please see the vma manager for more information.

Parameters

structdrm_gem_object**objs

drm_gem_objects to lock

intcount

Number of objects inobjs

structww_acquire_ctx*acquire_ctx

structww_acquire_ctx that will be initialized aspart of tracking this set of locked reservations.

Description

Once you’ve locked your reservations, you’ll want to set up spacefor your shared fences (if applicable), submit your job, thendrm_gem_unlock_reservations().

Parameters

structdrm_gem_lru*lru

The LRU to initialize

structmutex*lock

The lock protecting the LRU

Parameters

structdrm_gem_object*obj

The GEM object to remove from current LRU

Description

If the object is currently in any LRU, remove it.

Parameters

structdrm_gem_lru*lru

The LRU to move the object into.

structdrm_gem_object*obj

The GEM object to move into this LRU

Description

Likedrm_gem_lru_move_tail but lru lock must be held

Parameters

structdrm_gem_lru*lru

The LRU to move the object into.

structdrm_gem_object*obj

The GEM object to move into this LRU

Description

If the object is already in this LRU it will be moved to thetail. Otherwise it will be removed from whichever other LRUit is in (if any) and moved into this LRU.

Parameters

structdrm_gem_lru*lru

The LRU to scan

unsignedintnr_to_scan

The number of pages to try to reclaim

unsignedlong*remaining

The number of pages left to reclaim, should be initialized by caller

bool(*shrink)(structdrm_gem_object*obj,structww_acquire_ctx*ticket)

Callback to try to shrink/reclaim the object.

structww_acquire_ctx*ticket

Optional ww_acquire_ctx context to use for locking

Description

If the shrink callback succeeds, it is expected that the drivermove the object out of this LRU.

If the LRU possibly contain active buffers, it is the responsibilityof the shrink callback to check for this (ie.dma_resv_test_signaled())or if necessary block until the buffer becomes idle.

Parameters

structdrm_gem_object*obj

obj in question

Definition:

struct drm_gem_dma_object {    struct drm_gem_object base;    dma_addr_t dma_addr;    struct sg_table *sgt;    void *vaddr;    bool map_noncoherent;};

Members

base

base GEM object

dma_addr

DMA address of the backing memory

sgt

scatter/gather table for imported PRIME buffers. The table can havemore than one entry but they are guaranteed to have contiguousDMA addresses.

vaddr

kernel virtual address of the backing memory

map_noncoherent

if true, the GEM object is backed by non-coherent memory

Parameters

structdrm_gem_object*obj

GEM object to free

Description

This function wrapsdrm_gem_dma_free_object(). Drivers that employ the DMA helpersshould use it as theirdrm_gem_object_funcs.free handler.

Parameters

structdrm_printer*p

DRM printer

unsignedintindent

Tab indentation level

conststructdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_dma_print_info(). Drivers that employ the DMA helpersshould use this function as theirdrm_gem_object_funcs.print_info handler.

Parameters

structdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_dma_get_sg_table(). Drivers that employ the DMA helpers shoulduse it as theirdrm_gem_object_funcs.get_sg_table handler.

Return

A pointer to the scatter/gather table of pinned pages or NULL on failure.

Parameters

structdrm_gem_object*obj

GEM object

structvm_area_struct*vma

VMA for the area to be mapped

Description

This function wrapsdrm_gem_dma_mmap(). Drivers that employ the dma helpers shoulduse it as theirdrm_gem_object_funcs.mmap handler.

Return

0 on success or a negative error code on failure.

Parameters

dumb_create_func

callback function for .dumb_create

Description

This macro provides a shortcut for setting the default GEM operations in thedrm_driver structure.

This macro is a variant of DRM_GEM_DMA_DRIVER_OPS for drivers thatoverride the default implementation ofstructrm_driver.dumb_create. UseDRM_GEM_DMA_DRIVER_OPS if possible. Drivers that require a virtual addresson imported buffers should useDRM_GEM_DMA_DRIVER_OPS_VMAP_WITH_DUMB_CREATE() instead.

Parameters

dumb_create_func

callback function for .dumb_create

Description

This macro provides a shortcut for setting the default GEM operations in thedrm_driver structure for drivers that need the virtual address also onimported buffers.

This macro is a variant of DRM_GEM_DMA_DRIVER_OPS_VMAP for drivers thatoverride the default implementation ofstructdrm_driver.dumb_create. UseDRM_GEM_DMA_DRIVER_OPS_VMAP if possible. Drivers that do not require avirtual address on imported buffers should useDRM_GEM_DMA_DRIVER_OPS_WITH_DUMB_CREATE() instead.

Parameters

name

name for the generated structure

Description

This macro autogenerates a suitablestructfile_operations for DMA baseddrivers, which can be assigned todrm_driver.fops. Note that this structurecannot be shared between drivers, because it contains a reference to thecurrent module using THIS_MODULE.

Note that the declaration is already marked as static - if you need anon-static version of this you’re probably doing it wrong and will break theTHIS_MODULE reference by accident.

Parameters

structdrm_device*drm

DRM device

size_tsize

size of the object to allocate

Description

This function creates a DMA GEM object and allocates memory as backing store.The allocated memory will occupy a contiguous chunk of bus address space.

For devices that are directly connected to the memory bus then the allocatedmemory will be physically contiguous. For devices that access through anIOMMU, then the allocated memory is not expected to be physically contiguousbecause having contiguous IOVAs is sufficient to meet a devices DMArequirements.

Return

Astructdrm_gem_dma_object * on success or anERR_PTR()-encoded negativeerror code on failure.

Parameters

structdrm_gem_dma_object*dma_obj

DMA GEM object to free

Description

This function frees the backing memory of the DMA GEM object, cleans up theGEM object state and frees the memory used to store the object itself.If the buffer is imported and the virtual address is set, it is released.

Parameters

structdrm_file*file_priv

DRM file-private structure to create the dumb buffer for

structdrm_device*drm

DRM device

structdrm_mode_create_dumb*args

IOCTL data

Description

This aligns the pitch and size arguments to the minimum required. This isan internal helper that can be wrapped by a driver to account for hardwarewith more specific alignment requirements. It should not be used directlyas theirdrm_driver.dumb_create callback.

Return

0 on success or a negative error code on failure.

Parameters

structdrm_file*file_priv

DRM file-private structure to create the dumb buffer for

structdrm_device*drm

DRM device

structdrm_mode_create_dumb*args

IOCTL data

Description

This function computes the pitch of the dumb buffer and rounds it up to aninteger number of bytes per pixel. Drivers for hardware that doesn’t haveany additional restrictions on the pitch can directly use this function astheirdrm_driver.dumb_create callback.

For hardware with additional restrictions, drivers can adjust the fieldsset up by userspace and pass the IOCTL data along to thedrm_gem_dma_dumb_create_internal() function.

Return

0 on success or a negative error code on failure.

Parameters

structfile*filp

file object

unsignedlongaddr

memory address

unsignedlonglen

buffer size

unsignedlongpgoff

page offset

unsignedlongflags

memory flags

Description

This function is used in noMMU platforms to propose address mappingfor a given buffer.It’s intended to be used as a direct handler for the structfile_operations.get_unmapped_area operation.

Return

mapping address on success or a negative error code on failure.

Parameters

conststructdrm_gem_dma_object*dma_obj

DMA GEM object

structdrm_printer*p

DRM printer

unsignedintindent

Tab indentation level

Description

This function prints dma_addr and vaddr for use in e.g. debugfs output.

Parameters

structdrm_gem_dma_object*dma_obj

DMA GEM object

Description

This function exports a scatter/gather table by calling the standardDMA mapping API.

Return

A pointer to the scatter/gather table of pinned pages or NULL on failure.

Parameters

structdrm_device*dev

device to import into

structdma_buf_attachment*attach

DMA-BUF attachment

structsg_table*sgt

scatter/gather table of pinned pages

Description

This function imports a scatter/gather table exported via DMA-BUF byanother driver. Imported buffers must be physically contiguous in memory(i.e. the scatter/gather table must contain a single entry). Drivers thatuse the DMA helpers should set this as theirdrm_driver.gem_prime_import_sg_table callback.

Return

A pointer to a newly created GEM object or an ERR_PTR-encoded negativeerror code on failure.

Parameters

structdrm_gem_dma_object*dma_obj

DMA GEM object

structiosys_map*map

Returns the kernel virtual address of the DMA GEM object’s backingstore.

Description

This function maps a buffer into the kernel’s virtual address space.Since the DMA buffers are already mapped into the kernel virtual addressspace this simply returns the cached virtual address.

Return

0 on success, or a negative error code otherwise.

Parameters

structdrm_gem_dma_object*dma_obj

DMA GEM object

structvm_area_struct*vma

VMA for the area to be mapped

Description

This function maps a buffer into a userspace process’s address space.In addition to the usual GEM VMA setup it immediately faults in the entireobject instead of using on-demand faulting.

Return

0 on success or a negative error code on failure.

Parameters

structdrm_device*dev

DRM device

structdma_buf_attachment*attach

DMA-BUF attachment

structsg_table*sgt

Scatter/gather table of pinned pages

Description

This function imports a scatter/gather table usingdrm_gem_dma_prime_import_sg_table() and usesdma_buf_vmap() to get the kernelvirtual address. This ensures that a DMA GEM object always has its virtualaddress set. This address is released when the object is freed.

This function can be used as thedrm_driver.gem_prime_import_sg_tablecallback. TheDRM_GEM_DMA_DRIVER_OPS_VMAP macro provides a shortcut to setthe necessary DRM driver operations.

Return

A pointer to a newly created GEM object or an ERR_PTR-encoded negativeerror code on failure.

Definition:

struct drm_gem_shmem_object {    struct drm_gem_object base;    struct page **pages;    refcount_t pages_use_count;    refcount_t pages_pin_count;    int madv;    struct list_head madv_list;    struct sg_table *sgt;    void *vaddr;    refcount_t vmap_use_count;    bool pages_mark_dirty_on_put : 1;    bool pages_mark_accessed_on_put : 1;    bool map_wc : 1;};

Members

base

Base GEM object

pages

Page table

pages_use_count

Reference count on the pages table.The pages are put when the count reaches zero.

pages_pin_count

Reference count on the pinned pages table.

Pages are hard-pinned and reside in memory if countgreater than zero. Otherwise, when count is zero, the pages areallowed to be evicted and purged by memory shrinker.

madv

State for madvise

0 is active/inuse.A negative value is the object is purged.Positive values are driver specific and not used by the helpers.

madv_list

List entry for madvise tracking

Typically used by drivers to track purgeable objects

sgt

Scatter/gather table for imported PRIME buffers

vaddr

Kernel virtual address of the backing memory

vmap_use_count

Reference count on the virtual address.The address are un-mapped when the count reaches zero.

pages_mark_dirty_on_put

Mark pages as dirty when they are put.

pages_mark_accessed_on_put

Mark pages as accessed when they are put.

map_wc

map object write-combined (instead of using shmem defaults).

Parameters

structdrm_gem_object*obj

GEM object to free

Description

This function wrapsdrm_gem_shmem_free(). Drivers that employ the shmem helpersshould use it as theirdrm_gem_object_funcs.free handler.

Parameters

structdrm_printer*p

DRM printer

unsignedintindent

Tab indentation level

conststructdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_shmem_print_info(). Drivers that employ the shmem helpers shoulduse this function as theirdrm_gem_object_funcs.print_info handler.

Parameters

structdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_shmem_pin(). Drivers that employ the shmem helpers shoulduse it as theirdrm_gem_object_funcs.pin handler.

Parameters

structdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_shmem_unpin(). Drivers that employ the shmem helpers shoulduse it as theirdrm_gem_object_funcs.unpin handler.

Parameters

structdrm_gem_object*obj

GEM object

Description

This function wrapsdrm_gem_shmem_get_sg_table(). Drivers that employ the shmem helpers shoulduse it as theirdrm_gem_object_funcs.get_sg_table handler.

Return

A pointer to the scatter/gather table of pinned pages or error pointer on failure.

Parameters

structdrm_gem_object*obj

GEM object

structvm_area_struct*vma

VMA for the area to be mapped