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
11struct 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 */
41enum 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};
55
56enum xe_uc_fw_type {
57	XE_UC_FW_TYPE_GUC = 0,
58	XE_UC_FW_TYPE_HUC,
59	XE_UC_FW_TYPE_GSC,
60	XE_UC_FW_NUM_TYPES
61};
62
63/**
64 * struct xe_uc_fw_version - Version for XE micro controller firmware
65 */
66struct xe_uc_fw_version {
67	/** @major: major version of the FW */
68	u16 major;
69	/** @minor: minor version of the FW */
70	u16 minor;
71	/** @patch: patch version of the FW */
72	u16 patch;
73	/** @build: build version of the FW (not always available) */
74	u16 build;
75};
76
77enum xe_uc_fw_version_types {
78	XE_UC_FW_VER_RELEASE,
79	XE_UC_FW_VER_COMPATIBILITY,
80	XE_UC_FW_VER_TYPE_COUNT
81};
82
83/**
84 * struct xe_uc_fw - XE micro controller firmware
85 */
86struct xe_uc_fw {
87	/** @type: type uC firmware */
88	enum xe_uc_fw_type type;
89	union {
90		/** @status: firmware load status */
91		const enum xe_uc_fw_status status;
92		/**
93		 * @__status: private firmware load status - only to be used
94		 * by firmware laoding code
95		 */
96		enum xe_uc_fw_status __status;
97	};
98	/** @path: path to uC firmware */
99	const char *path;
100	/** @user_overridden: user provided path to uC firmware via modparam */
101	bool user_overridden;
102	/**
103	 * @full_ver_required: driver still under development and not ready
104	 * for backward-compatible firmware. To be used only for **new**
105	 * platforms, i.e. still under require_force_probe protection and not
106	 * supported by i915.
107	 */
108	bool full_ver_required;
109	/** @size: size of uC firmware including css header */
110	size_t size;
111
112	/** @bo: XE BO for uC firmware */
113	struct xe_bo *bo;
114
115	/** @has_gsc_headers: whether the FW image starts with GSC headers */
116	bool has_gsc_headers;
117
118	/*
119	 * The firmware build process will generate a version header file with
120	 * major and minor version defined. The versions are built into CSS
121	 * header of firmware. The xe kernel driver set the minimal firmware
122	 * version required per platform.
123	 */
124
125	/** @versions: FW versions wanted and found */
126	struct {
127		/** @versions.wanted: firmware version wanted by platform */
128		struct xe_uc_fw_version wanted;
129		/**
130		 * @versions.wanted_type: type of firmware version wanted
131		 * (release vs compatibility)
132		 */
133		enum xe_uc_fw_version_types wanted_type;
134		/** @versions.found: fw versions found in firmware blob */
135		struct xe_uc_fw_version found[XE_UC_FW_VER_TYPE_COUNT];
136	} versions;
137
138	/** @rsa_size: RSA size */
139	u32 rsa_size;
140	/** @ucode_size: micro kernel size */
141	u32 ucode_size;
142	/** @css_offset: offset within the blob at which the CSS is located */
143	u32 css_offset;
144
145	/** @private_data_size: size of private data found in uC css header */
146	u32 private_data_size;
147};
148
149#endif
150