xe_pagefault_types.h

  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