xref: /linux/drivers/hid/intel-ish-hid/ishtp/loader.h (revision b50ecc5aca4d18f1f0c4942f5c797bc85edef144)
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * ISHTP firmware loader header
4  *
5  * Copyright (c) 2024, Intel Corporation.
6  */
7 
8 #ifndef _ISHTP_LOADER_H_
9 #define _ISHTP_LOADER_H_
10 
11 #include <linux/bits.h>
12 #include <linux/jiffies.h>
13 #include <linux/sizes.h>
14 #include <linux/types.h>
15 
16 #include "ishtp-dev.h"
17 
18 struct work_struct;
19 
20 #define LOADER_MSG_SIZE \
21 	(IPC_PAYLOAD_SIZE - sizeof(struct ishtp_msg_hdr))
22 
23 /*
24  * ISHTP firmware loader protocol definition
25  */
26 #define LOADER_CMD_XFER_QUERY		0	/* SW -> FW */
27 #define LOADER_CMD_XFER_FRAGMENT	1	/* SW -> FW */
28 #define LOADER_CMD_START		2	/* SW -> FW */
29 
30 /* Only support DMA mode */
31 #define LOADER_XFER_MODE_DMA BIT(0)
32 
33 /**
34  * union loader_msg_header - ISHTP firmware loader message header
35  * @command: Command type
36  * @is_response: Indicates if the message is a response
37  * @has_next: Indicates if there is a next message
38  * @reserved: Reserved for future use
39  * @status: Status of the message
40  * @val32: entire header as a 32-bit value
41  */
42 union loader_msg_header {
43 	struct {
44 		__u32 command:7;
45 		__u32 is_response:1;
46 		__u32 has_next:1;
47 		__u32 reserved:15;
48 		__u32 status:8;
49 	};
50 	__u32 val32;
51 };
52 
53 /**
54  * struct loader_xfer_query - ISHTP firmware loader transfer query packet
55  * @header: Header of the message
56  * @image_size: Size of the image
57  */
58 struct loader_xfer_query {
59 	__le32 header;
60 	__le32 image_size;
61 };
62 
63 /**
64  * struct loader_version - ISHTP firmware loader version
65  * @value: Value of the version
66  * @major: Major version
67  * @minor: Minor version
68  * @hotfix: Hotfix version
69  * @build: Build version
70  */
71 struct loader_version {
72 	union {
73 		__le32 value;
74 		struct {
75 			__u8 major;
76 			__u8 minor;
77 			__u8 hotfix;
78 			__u8 build;
79 		};
80 	};
81 };
82 
83 /**
84  * struct loader_capability - ISHTP firmware loader capability
85  * @max_fw_image_size: Maximum firmware image size
86  * @support_mode: Support mode
87  * @reserved: Reserved for future use
88  * @platform: Platform
89  * @max_dma_buf_size: Maximum DMA buffer size, multiples of 4096
90  */
91 struct loader_capability {
92 	__le32 max_fw_image_size;
93 	__le16 support_mode;
94 	__u8 reserved;
95 	__u8 platform;
96 	__le32 max_dma_buf_size;
97 };
98 
99 /**
100  * struct loader_xfer_query_ack - ISHTP firmware loader transfer query acknowledgment
101  * @header: Header of the message
102  * @version_major: ISH Major version
103  * @version_minor: ISH Minor version
104  * @version_hotfix: ISH Hotfix version
105  * @version_build: ISH Build version
106  * @protocol_version: Protocol version
107  * @loader_version: Loader version
108  * @capability: Loader capability
109  */
110 struct loader_xfer_query_ack {
111 	__le32 header;
112 	__le16 version_major;
113 	__le16 version_minor;
114 	__le16 version_hotfix;
115 	__le16 version_build;
116 	__le32 protocol_version;
117 	struct loader_version loader_version;
118 	struct loader_capability capability;
119 };
120 
121 /**
122  * struct loader_xfer_fragment - ISHTP firmware loader transfer fragment
123  * @header: Header of the message
124  * @xfer_mode: Transfer mode
125  * @offset: Offset
126  * @size: Size
127  * @is_last: Is last
128  */
129 struct loader_xfer_fragment {
130 	__le32 header;
131 	__le32 xfer_mode;
132 	__le32 offset;
133 	__le32 size;
134 	__le32 is_last;
135 };
136 
137 /**
138  * struct loader_xfer_fragment_ack - ISHTP firmware loader transfer fragment acknowledgment
139  * @header: Header of the message
140  */
141 struct loader_xfer_fragment_ack {
142 	__le32 header;
143 };
144 
145 /**
146  * struct fragment_dscrpt - ISHTP firmware loader fragment descriptor
147  * @ddr_adrs: The address in host DDR
148  * @fw_off: The offset of the fragment in the fw image
149  * @length: The length of the fragment
150  */
151 struct fragment_dscrpt {
152 	__le64 ddr_adrs;
153 	__le32 fw_off;
154 	__le32 length;
155 };
156 
157 #define FRAGMENT_MAX_NUM \
158 	((LOADER_MSG_SIZE - sizeof(struct loader_xfer_dma_fragment)) / \
159 	 sizeof(struct fragment_dscrpt))
160 
161 /**
162  * struct loader_xfer_dma_fragment - ISHTP firmware loader transfer DMA fragment
163  * @fragment: Fragment
164  * @fragment_cnt: How many descriptors in the fragment_tbl
165  * @fragment_tbl: Fragment table
166  */
167 struct loader_xfer_dma_fragment {
168 	struct loader_xfer_fragment fragment;
169 	__le32 fragment_cnt;
170 	struct fragment_dscrpt fragment_tbl[] __counted_by(fragment_cnt);
171 };
172 
173 /**
174  * struct loader_start - ISHTP firmware loader start
175  * @header: Header of the message
176  */
177 struct loader_start {
178 	__le32 header;
179 };
180 
181 /**
182  * struct loader_start_ack - ISHTP firmware loader start acknowledgment
183  * @header: Header of the message
184  */
185 struct loader_start_ack {
186 	__le32 header;
187 };
188 
189 union loader_recv_message {
190 	__le32 header;
191 	struct loader_xfer_query_ack query_ack;
192 	struct loader_xfer_fragment_ack fragment_ack;
193 	struct loader_start_ack start_ack;
194 	__u8 raw_data[LOADER_MSG_SIZE];
195 };
196 
197 /*
198  * ISHTP firmware loader internal use
199  */
200 /* ISHTP firmware loader command timeout */
201 #define ISHTP_LOADER_TIMEOUT msecs_to_jiffies(100)
202 
203 /* ISHTP firmware loader retry times */
204 #define ISHTP_LOADER_RETRY_TIMES 3
205 
206 /**
207  * struct ish_firmware_variant - ISH firmware variant
208  * @device: PCI Device ID
209  * @filename: The firmware file name
210  */
211 struct ish_firmware_variant {
212 	unsigned short device;
213 	const char *filename;
214 };
215 
216 /*
217  * ISHTP firmware loader API for ISHTP hbm
218  */
219 
220 /* ISHTP capability bit for firmware loader */
221 #define ISHTP_SUPPORT_CAP_LOADER BIT(4)
222 
223 /* Firmware loader address */
224 #define ISHTP_LOADER_CLIENT_ADDR 16
225 
226 /**
227  * ishtp_loader_work - The work function to start the firmware loading process
228  * @work: The work structure
229  */
230 void ishtp_loader_work(struct work_struct *work);
231 
232 /* ISH Manifest alignment in binary is 4KB aligned */
233 #define ISH_MANIFEST_ALIGNMENT SZ_4K
234 
235 /* Signature for ISH global manifest */
236 #define ISH_GLOBAL_SIG 0x47485349	/* FourCC 'I', 'S', 'H', 'G' */
237 
238 struct version_in_manifest {
239 	__le16 major;
240 	__le16 minor;
241 	__le16 hotfix;
242 	__le16 build;
243 };
244 
245 /**
246  * struct ish_global_manifest - global manifest for ISH
247  * @sig_fourcc: Signature FourCC, should be 'I', 'S', 'H', 'G'.
248  * @len: Length of the manifest.
249  * @header_version: Version of the manifest header.
250  * @flags: Flags for additional information.
251  * @base_ver: Base version of Intel's released firmware.
252  * @reserved: Reserved space for future use.
253  * @prj_ver: Vendor-customized project version.
254  */
255 struct ish_global_manifest {
256 	__le32 sig_fourcc;
257 	__le32 len;
258 	__le32 header_version;
259 	__le32 flags;
260 	struct version_in_manifest base_ver;
261 	__le32 reserved[13];
262 	struct version_in_manifest prj_ver;
263 };
264 
265 #endif /* _ISHTP_LOADER_H_ */
266