loader.h

  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
 18struct 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 */
 42union 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 */
 58struct 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 */
 71struct 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 */
 91struct 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 */
110struct 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 */
129struct 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 */
141struct 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 */
151struct 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 */
167struct 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 */
177struct 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 */
185struct loader_start_ack {
186	__le32 header;
187};
188
189union 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 */
211struct 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 */
230void 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
238struct 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 */
255struct 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_ */