2 * This file is part of the coreboot project.
4 * Copyright 2015 Google, Inc.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
25 struct nhlt_format_config
;
28 * Non HD Audio ACPI support. This table is typically used for Intel Smart
29 * Sound Technology DSP. It provides a way to encode opaque settings in
32 * While the structure fields of the NHLT structs are exposed below
33 * the SoC/chipset code should be the only other user manipulating the
34 * fields directly aside from the library itself.
36 * The NHLT table consists of endpoints which in turn contain different
37 * supporting stream formats. Each endpoint may contain a device specific
38 * configuration payload as well as each stream format.
40 * Most code should use the SoC variants of the functions because
41 * there is required logic needed to be performed by the SoC. The SoC
42 * code should be abstracting the inner details of these functions that
43 * specically apply to NHLT objects for that SoC.
45 * An example sequence:
48 * ep = nhlt_add_endpoint()
49 * nhlt_endpoint_append_config(ep)
50 * nhlt_endpoint_add_formats(ep)
51 * nhlt_soc_serialize()
54 /* Obtain an nhlt object for adding endpoints. Returns NULL on error. */
55 struct nhlt
*nhlt_init(void);
57 /* Return the size of the NHLT table including APCI header. */
58 size_t nhlt_current_size(struct nhlt
*nhlt
);
61 * Helper functions for adding NHLT devices utilizing an nhlt_endp_descriptor
65 struct nhlt_endp_descriptor
{
66 /* NHLT endpoint types. */
72 /* Optional endpoint specific configuration data. */
75 /* Formats supported for endpoint. */
76 const struct nhlt_format_config
*formats
;
81 * Add the number of endpoints described by each descriptor. The virtual bus
82 * id for each descriptor is the default value of 0.
83 * Returns < 0 on error, 0 on success.
85 int nhlt_add_endpoints(struct nhlt
*nhlt
,
86 const struct nhlt_endp_descriptor
*epds
,
90 * Add the number of endpoints associated with a single NHLT SSP instance id.
91 * Each endpoint described in the endpoint descriptor array uses the provided
92 * virtual bus id. Returns < 0 on error, 0 on success.
94 int nhlt_add_ssp_endpoints(struct nhlt
*nhlt
, int virtual_bus_id
,
95 const struct nhlt_endp_descriptor
*epds
, size_t num_epds
);
98 * Add endpoint to NHLT object. Returns NULL on error.
100 * generic nhlt_add_endpoint() is called by the SoC code to provide
101 * the specific assumptions/uses for NHLT for that platform. All fields
102 * are the NHLT enumerations found within this header file.
104 struct nhlt_endpoint
*nhlt_add_endpoint(struct nhlt
*nhlt
, int link_type
,
105 int device_type
, int dir
,
106 uint16_t vid
, uint16_t did
);
109 * Append blob of configuration to the endpoint proper. Returns 0 on
110 * success, < 0 on error. A copy of the configuration is made so any
111 * resources pointed to by config can be freed after the call.
113 int nhlt_endpoint_append_config(struct nhlt_endpoint
*endpoint
,
114 const void *config
, size_t config_sz
);
116 /* Add a format type to the provided endpoint. Returns NULL on error. */
117 struct nhlt_format
*nhlt_add_format(struct nhlt_endpoint
*endpoint
,
120 int container_bits_per_sample
,
121 int valid_bits_per_sample
,
122 uint32_t speaker_mask
);
125 * Append blob of configuration to the format proper. Returns 0 on
126 * success, < 0 on error. A copy of the configuration is made so any
127 * resources pointed to by config can be freed after the call.
129 int nhlt_format_append_config(struct nhlt_format
*format
, const void *config
,
133 * Add num_formats described by formats to the endpoint. This function
134 * effectively wraps nhlt_add_format() and nhlt_format_config() using the
135 * data found in each nhlt_format_config object. Returns 0 on success, < 0
138 int nhlt_endpoint_add_formats(struct nhlt_endpoint
*endpoint
,
139 const struct nhlt_format_config
*formats
,
143 * Increment the instance id for a given link type. This function is
144 * used for marking a device being completely added to the NHLT object.
145 * Subsequent endpoints added to the nhlt object with the same link type
146 * will use incremented instance id.
148 void nhlt_next_instance(struct nhlt
*nhlt
, int link_type
);
151 * Serialize NHLT object to ACPI table. Take in the beginning address of where
152 * the table will reside and return the address of the next ACPI table. On
153 * error 0 will be returned. The NHLT object is no longer valid after this
154 * function is called.
156 uintptr_t nhlt_serialize(struct nhlt
*nhlt
, uintptr_t acpi_addr
);
159 * Serialize NHLT object to ACPI table. Take in the beginning address of where
160 * the table will reside oem_id and oem_table_id and return the address of the
161 * next ACPI table. On error 0 will be returned. The NHLT object is no longer
162 * valid after thisfunction is called.
164 uintptr_t nhlt_serialize_oem_overrides(struct nhlt
*nhlt
, uintptr_t acpi_addr
,
165 const char *oem_id
, const char *oem_table_id
,
166 uint32_t oem_revision
);
169 * While very similar to nhlt_serialize() the SoC specific function allows
170 * the chipset to perform any needed accounting work such as updating ACPI
171 * field references for the serialized structure.
173 uintptr_t nhlt_soc_serialize(struct nhlt
*nhlt
, uintptr_t acpi_addr
);
176 * While very similar to nhlt_serialize_oem_overrides() the SoC specific
177 * function allows the chipset to perform any needed accounting work such
178 * as updating ACPI field references for the serialized structure.
180 uintptr_t nhlt_soc_serialize_oem_overrides(struct nhlt
*nhlt
,
181 uintptr_t acpi_addr
, const char *oem_id
, const char *oem_table_id
,
182 uint32_t oem_revision
);
184 /* Link and device types. */
194 NHLT_SSP_DEV_BT
, /* Bluetooth */
197 NHLT_SSP_DEV_RESERVED
,
198 NHLT_SSP_DEV_I2S
= 4,
205 /* Endpoint direction. */
209 NHLT_DIR_BIDIRECTIONAL
,
212 /* Channel Mask for an endpoint. While they are prefixed with 'SPEAKER' the
213 * channel masks are also used for capture devices. */
215 SPEAKER_FRONT_LEFT
= 1 << 0,
216 SPEAKER_FRONT_RIGHT
= 1 << 1,
217 SPEAKER_FRONT_CENTER
= 1 << 2,
218 SPEAKER_LOW_FREQUENCY
= 1 << 3,
219 SPEAKER_BACK_LEFT
= 1 << 4,
220 SPEAKER_BACK_RIGHT
= 1 << 5,
221 SPEAKER_FRONT_LEFT_OF_CENTER
= 1 << 6,
222 SPEAKER_FRONT_RIGHT_OF_CENTER
= 1 << 7,
223 SPEAKER_BACK_CENTER
= 1 << 8,
224 SPEAKER_SIDE_LEFT
= 1 << 9,
225 SPEAKER_SIDE_RIGHT
= 1 << 10,
226 SPEAKER_TOP_CENTER
= 1 << 11,
227 SPEAKER_TOP_FRONT_LEFT
= 1 << 12,
228 SPEAKER_TOP_FRONT_CENTER
= 1 << 13,
229 SPEAKER_TOP_FRONT_RIGHT
= 1 << 14,
230 SPEAKER_TOP_BACK_LEFT
= 1 << 15,
231 SPEAKER_TOP_BACK_CENTER
= 1 << 16,
232 SPEAKER_TOP_BACK_RIGHT
= 1 << 17,
236 /* Supporting structures. Only SoC/chipset and the library code directly should
237 * be manipulating these structures. */
245 struct nhlt_specific_config
{
250 struct nhlt_waveform
{
252 uint16_t num_channels
;
253 uint32_t samples_per_second
;
254 uint32_t bytes_per_second
;
255 uint16_t block_align
;
256 uint16_t bits_per_sample
;
258 uint16_t valid_bits_per_sample
;
259 uint32_t channel_mask
;
260 struct sub_format sub_format
;
264 struct nhlt_waveform waveform
;
265 struct nhlt_specific_config config
;
269 * This struct is used by nhlt_endpoint_add_formats() for easily adding
270 * waveform formats with associated settings file.
272 struct nhlt_format_config
{
275 int container_bits_per_sample
;
276 int valid_bits_per_sample
;
277 uint32_t speaker_mask
;
278 const char *settings_file
;
281 /* Arbitrary max number of formats per endpoint. */
282 #define MAX_FORMATS 2
283 struct nhlt_endpoint
{
289 uint16_t revision_id
;
290 uint32_t subsystem_id
;
293 uint8_t virtual_bus_id
;
294 struct nhlt_specific_config config
;
296 struct nhlt_format formats
[MAX_FORMATS
];
299 #define MAX_ENDPOINTS 8
301 uint32_t subsystem_id
;
302 uint8_t num_endpoints
;
303 struct nhlt_endpoint endpoints
[MAX_ENDPOINTS
];
304 uint8_t current_instance_id
[NHLT_MAX_LINK_TYPES
];
307 struct nhlt_tdm_config
{
308 uint8_t virtual_slot
;
317 struct nhlt_dmic_array_config
{
318 struct nhlt_tdm_config tdm_config
;
323 * Microphone array definitions may be found here:
324 * https://msdn.microsoft.com/en-us/library/windows/hardware/dn613960%28v=vs.85%29.aspx
327 NHLT_MIC_ARRAY_2CH_SMALL
= 0xa,
328 NHLT_MIC_ARRAY_2CH_BIG
= 0xb,
329 NHLT_MIC_ARRAY_4CH_1ST_GEOM
= 0xc,
330 NHLT_MIC_ARRAY_4CH_L_SHAPED
= 0xd,
331 NHLT_MIC_ARRAY_4CH_2ND_GEOM
= 0xe,
332 NHLT_MIC_ARRAY_VENDOR_DEFINED
= 0xf,