1/* SPDX-License-Identifier: MIT */
2/*
3 * Copyright © 2025 Intel Corporation
4 */
5
6#ifndef _XE_PAGEFAULT_TYPES_H_
7#define _XE_PAGEFAULT_TYPES_H_
8
9#include <linux/workqueue.h>
10
11struct xe_gt;
12struct xe_pagefault;
13
14/** enum xe_pagefault_access_type - Xe page fault access type */
15enum xe_pagefault_access_type {
16 /** @XE_PAGEFAULT_ACCESS_TYPE_READ: Read access type */
17 XE_PAGEFAULT_ACCESS_TYPE_READ = 0,
18 /** @XE_PAGEFAULT_ACCESS_TYPE_WRITE: Write access type */
19 XE_PAGEFAULT_ACCESS_TYPE_WRITE = 1,
20 /** @XE_PAGEFAULT_ACCESS_TYPE_ATOMIC: Atomic access type */
21 XE_PAGEFAULT_ACCESS_TYPE_ATOMIC = 2,
22};
23
24/** enum xe_pagefault_type - Xe page fault type */
25enum xe_pagefault_type {
26 /** @XE_PAGEFAULT_TYPE_NOT_PRESENT: Not present */
27 XE_PAGEFAULT_TYPE_NOT_PRESENT = 0,
28 /** @XE_PAGEFAULT_TYPE_WRITE_ACCESS_VIOLATION: Write access violation */
29 XE_PAGEFAULT_TYPE_WRITE_ACCESS_VIOLATION = 1,
30 /** @XE_PAGEFAULT_TYPE_ATOMIC_ACCESS_VIOLATION: Atomic access violation */
31 XE_PAGEFAULT_TYPE_ATOMIC_ACCESS_VIOLATION = 2,
32};
33
34/** struct xe_pagefault_ops - Xe pagefault ops (producer) */
35struct xe_pagefault_ops {
36 /**
37 * @ack_fault: Ack fault
38 * @pf: Page fault
39 * @err: Error state of fault
40 *
41 * Page fault producer receives acknowledgment from the consumer and
42 * sends the result to the HW/FW interface.
43 */
44 void (*ack_fault)(struct xe_pagefault *pf, int err);
45};
46
47/**
48 * struct xe_pagefault - Xe page fault
49 *
50 * Generic page fault structure for communication between producer and consumer.
51 * Carefully sized to be 64 bytes. Upon a device page fault, the producer
52 * populates this structure, and the consumer copies it into the page-fault
53 * queue for deferred handling.
54 */
55struct xe_pagefault {
56 /**
57 * @gt: GT of fault
58 */
59 struct xe_gt *gt;
60 /**
61 * @consumer: State for the software handling the fault. Populated by
62 * the producer and may be modified by the consumer to communicate
63 * information back to the producer upon fault acknowledgment.
64 */
65 struct {
66 /** @consumer.page_addr: address of page fault */
67 u64 page_addr;
68 /** @consumer.asid: address space ID */
69 u32 asid;
70 /**
71 * @consumer.access_type: access type, u8 rather than enum to
72 * keep size compact
73 */
74 u8 access_type;
75 /**
76 * @consumer.fault_type: fault type, u8 rather than enum to
77 * keep size compact
78 */
79 u8 fault_type;
80#define XE_PAGEFAULT_LEVEL_NACK 0xff /* Producer indicates nack fault */
81 /** @consumer.fault_level: fault level */
82 u8 fault_level;
83 /** @consumer.engine_class: engine class */
84 u8 engine_class;
85 /** @consumer.engine_instance: engine instance */
86 u8 engine_instance;
87 /** consumer.reserved: reserved bits for future expansion */
88 u8 reserved[7];
89 } consumer;
90 /**
91 * @producer: State for the producer (i.e., HW/FW interface). Populated
92 * by the producer and should not be modified—or even inspected—by the
93 * consumer, except for calling operations.
94 */
95 struct {
96 /** @producer.private: private pointer */
97 void *private;
98 /** @producer.ops: operations */
99 const struct xe_pagefault_ops *ops;
100#define XE_PAGEFAULT_PRODUCER_MSG_LEN_DW 4
101 /**
102 * @producer.msg: page fault message, used by producer in fault
103 * acknowledgment to formulate response to HW/FW interface.
104 * Included in the page-fault message because the producer
105 * typically receives the fault in a context where memory cannot
106 * be allocated (e.g., atomic context or the reclaim path).
107 */
108 u32 msg[XE_PAGEFAULT_PRODUCER_MSG_LEN_DW];
109 } producer;
110};
111
112/**
113 * struct xe_pagefault_queue: Xe pagefault queue (consumer)
114 *
115 * Used to capture all device page faults for deferred processing. Size this
116 * queue to absorb the device’s worst-case number of outstanding faults.
117 */
118struct xe_pagefault_queue {
119 /**
120 * @data: Data in queue containing struct xe_pagefault, protected by
121 * @lock
122 */
123 void *data;
124 /** @size: Size of queue in bytes */
125 u32 size;
126 /** @head: Head pointer in bytes, moved by producer, protected by @lock */
127 u32 head;
128 /** @tail: Tail pointer in bytes, moved by consumer, protected by @lock */
129 u32 tail;
130 /** @lock: protects page fault queue */
131 spinlock_t lock;
132 /** @worker: to process page faults */
133 struct work_struct worker;
134};
135
136#endif
137

source code of linux/drivers/gpu/drm/xe/xe_pagefault_types.h