1 /* SPDX-License-Identifier: MIT */
2 /*
3  * Copyright © 2022 Intel Corporation
4  */
5 
6 #ifndef _XE_UC_FW_TYPES_H_
7 #define _XE_UC_FW_TYPES_H_
8 
9 #include <linux/types.h>
10 
11 struct xe_bo;
12 
13 /*
14  * +------------+---------------------------------------------------+
15  * |   PHASE    |           FIRMWARE STATUS TRANSITIONS             |
16  * +============+===================================================+
17  * |            |               UNINITIALIZED                       |
18  * +------------+-               /   |   \                         -+
19  * |            |   DISABLED <--/    |    \--> NOT_SUPPORTED        |
20  * | init_early |                    V                              |
21  * |            |                 SELECTED                          |
22  * +------------+-               /   |   \                         -+
23  * |            |    MISSING <--/    |    \--> ERROR                |
24  * |   fetch    |                    V                              |
25  * |            |                 AVAILABLE                         |
26  * +------------+-                   |   \                         -+
27  * |            |                    |    \--> INIT FAIL            |
28  * |   init     |                    V                              |
29  * |            |        /------> LOADABLE <----<-----------\       |
30  * +------------+-       \         /    \        \           \     -+
31  * |            |    LOAD FAIL <--<      \--> TRANSFERRED     \     |
32  * |   upload   |                  \           /   \          /     |
33  * |            |                   \---------/     \--> RUNNING    |
34  * +------------+---------------------------------------------------+
35  */
36 
37 /*
38  * FIXME: Ported from the i915 and this is state machine is way too complicated.
39  * Circle back and simplify this.
40  */
41 enum xe_uc_fw_status {
42 	XE_UC_FIRMWARE_NOT_SUPPORTED = -1, /* no uc HW */
43 	XE_UC_FIRMWARE_UNINITIALIZED = 0, /* used to catch checks done too early */
44 	XE_UC_FIRMWARE_DISABLED, /* disabled */
45 	XE_UC_FIRMWARE_SELECTED, /* selected the blob we want to load */
46 	XE_UC_FIRMWARE_MISSING, /* blob not found on the system */
47 	XE_UC_FIRMWARE_ERROR, /* invalid format or version */
48 	XE_UC_FIRMWARE_AVAILABLE, /* blob found and copied in mem */
49 	XE_UC_FIRMWARE_INIT_FAIL, /* failed to prepare fw objects for load */
50 	XE_UC_FIRMWARE_LOADABLE, /* all fw-required objects are ready */
51 	XE_UC_FIRMWARE_LOAD_FAIL, /* failed to xfer or init/auth the fw */
52 	XE_UC_FIRMWARE_TRANSFERRED, /* dma xfer done */
53 	XE_UC_FIRMWARE_RUNNING, /* init/auth done */
54 	XE_UC_FIRMWARE_PRELOADED, /* preloaded by the PF driver */
55 };
56 
57 enum xe_uc_fw_type {
58 	XE_UC_FW_TYPE_GUC = 0,
59 	XE_UC_FW_TYPE_HUC,
60 	XE_UC_FW_TYPE_GSC,
61 	XE_UC_FW_NUM_TYPES
62 };
63 
64 /**
65  * struct xe_uc_fw_version - Version for XE micro controller firmware
66  */
67 struct xe_uc_fw_version {
68 	/** @major: major version of the FW */
69 	u16 major;
70 	/** @minor: minor version of the FW */
71 	u16 minor;
72 	/** @patch: patch version of the FW */
73 	u16 patch;
74 	/** @build: build version of the FW (not always available) */
75 	u16 build;
76 };
77 
78 enum xe_uc_fw_version_types {
79 	XE_UC_FW_VER_RELEASE,
80 	XE_UC_FW_VER_COMPATIBILITY,
81 	XE_UC_FW_VER_TYPE_COUNT
82 };
83 
84 /**
85  * struct xe_uc_fw - XE micro controller firmware
86  */
87 struct xe_uc_fw {
88 	/** @type: type uC firmware */
89 	enum xe_uc_fw_type type;
90 	union {
91 		/** @status: firmware load status */
92 		const enum xe_uc_fw_status status;
93 		/**
94 		 * @__status: private firmware load status - only to be used
95 		 * by firmware laoding code
96 		 */
97 		enum xe_uc_fw_status __status;
98 	};
99 	/** @path: path to uC firmware */
100 	const char *path;
101 	/** @user_overridden: user provided path to uC firmware via modparam */
102 	bool user_overridden;
103 	/**
104 	 * @full_ver_required: driver still under development and not ready
105 	 * for backward-compatible firmware. To be used only for **new**
106 	 * platforms, i.e. still under require_force_probe protection and not
107 	 * supported by i915.
108 	 */
109 	bool full_ver_required;
110 	/** @size: size of uC firmware including css header */
111 	size_t size;
112 
113 	/** @bo: XE BO for uC firmware */
114 	struct xe_bo *bo;
115 
116 	/** @has_gsc_headers: whether the FW image starts with GSC headers */
117 	bool has_gsc_headers;
118 
119 	/*
120 	 * The firmware build process will generate a version header file with
121 	 * major and minor version defined. The versions are built into CSS
122 	 * header of firmware. The xe kernel driver set the minimal firmware
123 	 * version required per platform.
124 	 */
125 
126 	/** @versions: FW versions wanted and found */
127 	struct {
128 		/** @versions.wanted: firmware version wanted by platform */
129 		struct xe_uc_fw_version wanted;
130 		/**
131 		 * @versions.wanted_type: type of firmware version wanted
132 		 * (release vs compatibility)
133 		 */
134 		enum xe_uc_fw_version_types wanted_type;
135 		/** @versions.found: fw versions found in firmware blob */
136 		struct xe_uc_fw_version found[XE_UC_FW_VER_TYPE_COUNT];
137 	} versions;
138 
139 	/** @rsa_size: RSA size */
140 	u32 rsa_size;
141 	/** @ucode_size: micro kernel size */
142 	u32 ucode_size;
143 	/** @css_offset: offset within the blob at which the CSS is located */
144 	u32 css_offset;
145 
146 	/** @private_data_size: size of private data found in uC css header */
147 	u32 private_data_size;
148 };
149 
150 #endif
151