src/include/nhlt.h

   1 /*
   2  * This file is part of the coreboot project.
   3  *
   4  * Copyright 2015 Google, Inc.
   5  *
   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.
   9  *
  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.
  14  */
  15
  16 #ifndef _NHLT_H_
  17 #define _NHLT_H_
  18
  19 #include <stdint.h>
  20 #include <stddef.h>
  21
  22 struct nhlt;
  23 struct nhlt_endpoint;
  24 struct nhlt_format;
  25 struct nhlt_format_config;
  26
  27 /*
  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
  30  * the ACPI tables.
  31  *
  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.
  35  *
  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.
  39  *
  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.
  44  *
  45  * An example sequence:
  46  *
  47  * nhlt = nhlt_init()
  48  * ep = nhlt_add_endpoint()
  49  * nhlt_endpoint_append_config(ep)
  50  * nhlt_endpoint_add_formats(ep)
  51  * nhlt_soc_serialize()
  52  */
  53
  54 /* Obtain an nhlt object for adding endpoints. Returns NULL on error. */
  55 struct nhlt *nhlt_init(void);
  56
  57 /* Return the size of the NHLT table including APCI header. */
  58 size_t nhlt_current_size(struct nhlt *nhlt);
  59
  60 /*
  61  * Helper functions for adding NHLT devices utilizing an nhlt_endp_descriptor
  62  * to drive the logic.
  63  */
  64
  65 struct nhlt_endp_descriptor {
  66         /* NHLT endpoint types. */
  67         int link;
  68         int device;
  69         int direction;
  70         uint16_t vid;
  71         uint16_t did;
  72         /* Optional endpoint specific configuration data. */
  73         const void *cfg;
  74         size_t cfg_size;
  75         /* Formats supported for endpoint. */
  76         const struct nhlt_format_config *formats;
  77         size_t num_formats;
  78 };
  79
  80 /*
  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.
  84  */
  85 int nhlt_add_endpoints(struct nhlt *nhlt,
  86                         const struct nhlt_endp_descriptor *epds,
  87                         size_t num_epds);
  88
  89 /*
  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.
  93  */
  94 int nhlt_add_ssp_endpoints(struct nhlt *nhlt, int virtual_bus_id,
  95                 const struct nhlt_endp_descriptor *epds, size_t num_epds);
  96
  97 /*
  98  * Add endpoint to NHLT object. Returns NULL on error.
  99  *
 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.
 103  */
 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);
 107
 108 /*
 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.
 112  */
 113 int nhlt_endpoint_append_config(struct nhlt_endpoint *endpoint,
 114                                 const void *config, size_t config_sz);
 115
 116 /* Add a format type to the provided endpoint. Returns NULL on error. */
 117 struct nhlt_format *nhlt_add_format(struct nhlt_endpoint *endpoint,
 118                                         int num_channels,
 119                                         int sample_freq_khz,
 120                                         int container_bits_per_sample,
 121                                         int valid_bits_per_sample,
 122                                         uint32_t speaker_mask);
 123
 124 /*
 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.
 128  */
 129 int nhlt_format_append_config(struct nhlt_format *format, const void *config,
 130                                 size_t config_sz);
 131
 132 /*
 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
 136  * on error.
 137  */
 138 int nhlt_endpoint_add_formats(struct nhlt_endpoint *endpoint,
 139                                 const struct nhlt_format_config *formats,
 140                                 size_t num_formats);
 141
 142 /*
 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.
 147  */
 148 void nhlt_next_instance(struct nhlt *nhlt, int link_type);
 149
 150 /*
 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.
 155  */
 156 uintptr_t nhlt_serialize(struct nhlt *nhlt, uintptr_t acpi_addr);
 157
 158 /*
 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.
 163  */
 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
 167 /*
 168  * While very similar to nhlt_serialize() the SoC specific function allows
 169  * the chipset to perform any needed accounting work such as updating ACPI
 170  * field references for the serialized structure.
 171  */
 172 uintptr_t nhlt_soc_serialize(struct nhlt *nhlt, uintptr_t acpi_addr);
 173
 174 /*
 175  * While very similar to nhlt_serialize_oem_overrides() the SoC specific
 176  * function allows the chipset to perform any needed accounting work such
 177  * as updating ACPI field references for the serialized structure.
 178  */
 179 uintptr_t nhlt_soc_serialize_oem_overrides(struct nhlt *nhlt,
 180         uintptr_t acpi_addr, const char *oem_id, const char *oem_table_id);
 181
 182 /* Link and device types. */
 183 enum {
 184         NHLT_LINK_HDA,
 185         NHLT_LINK_DSP,
 186         NHLT_LINK_PDM,
 187         NHLT_LINK_SSP,
 188         NHLT_MAX_LINK_TYPES,
 189 };
 190
 191 enum {
 192         NHLT_SSP_DEV_BT, /* Bluetooth */
 193         NHLT_SSP_DEV_MODEM,
 194         NHLT_SSP_DEV_FM,
 195         NHLT_SSP_DEV_RESERVED,
 196         NHLT_SSP_DEV_I2S = 4,
 197 };
 198
 199 enum {
 200         NHLT_PDM_DEV,
 201 };
 202
 203 /* Endpoint direction. */
 204 enum {
 205         NHLT_DIR_RENDER,
 206         NHLT_DIR_CAPTURE,
 207         NHLT_DIR_BIDIRECTIONAL,
 208 };
 209
 210 /* Channel Mask for an endpoint. While they are prefixed with 'SPEAKER' the
 211  * channel masks are also used for capture devices. */
 212 enum {
 213         SPEAKER_FRONT_LEFT = 1 << 0,
 214         SPEAKER_FRONT_RIGHT = 1 << 1,
 215         SPEAKER_FRONT_CENTER = 1 << 2,
 216         SPEAKER_LOW_FREQUENCY = 1 << 3,
 217         SPEAKER_BACK_LEFT = 1 << 4,
 218         SPEAKER_BACK_RIGHT = 1 << 5,
 219         SPEAKER_FRONT_LEFT_OF_CENTER = 1 << 6,
 220         SPEAKER_FRONT_RIGHT_OF_CENTER = 1 << 7,
 221         SPEAKER_BACK_CENTER = 1 << 8,
 222         SPEAKER_SIDE_LEFT = 1 << 9,
 223         SPEAKER_SIDE_RIGHT = 1 << 10,
 224         SPEAKER_TOP_CENTER = 1 << 11,
 225         SPEAKER_TOP_FRONT_LEFT = 1 << 12,
 226         SPEAKER_TOP_FRONT_CENTER = 1 << 13,
 227         SPEAKER_TOP_FRONT_RIGHT = 1 << 14,
 228         SPEAKER_TOP_BACK_LEFT = 1 << 15,
 229         SPEAKER_TOP_BACK_CENTER = 1 << 16,
 230         SPEAKER_TOP_BACK_RIGHT = 1 << 17,
 231 };
 232
 233
 234 /* Supporting structures. Only SoC/chipset and the library code directly should
 235  * be manipulating these structures. */
 236 struct sub_format {
 237         uint32_t data1;
 238         uint16_t data2;
 239         uint16_t data3;
 240         uint8_t data4[8];
 241 };
 242
 243 struct nhlt_specific_config {
 244         uint32_t size;
 245         void *capabilities;
 246 };
 247
 248 struct nhlt_waveform {
 249         uint16_t tag;
 250         uint16_t num_channels;
 251         uint32_t samples_per_second;
 252         uint32_t bytes_per_second;
 253         uint16_t block_align;
 254         uint16_t bits_per_sample;
 255         uint16_t extra_size;
 256         uint16_t valid_bits_per_sample;
 257         uint32_t channel_mask;
 258         struct sub_format sub_format;
 259 };
 260
 261 struct nhlt_format {
 262         struct nhlt_waveform waveform;
 263         struct nhlt_specific_config config;
 264 };
 265
 266 /*
 267  * This struct is used by nhlt_endpoint_add_formats() for easily adding
 268  * waveform formats with associated settings file.
 269  */
 270 struct nhlt_format_config {
 271         int num_channels;
 272         int sample_freq_khz;
 273         int container_bits_per_sample;
 274         int valid_bits_per_sample;
 275         uint32_t speaker_mask;
 276         const char *settings_file;
 277 };
 278
 279 /* Arbitrary max number of formats per endpoint. */
 280 #define MAX_FORMATS 2
 281 struct nhlt_endpoint {
 282         uint32_t length;
 283         uint8_t link_type;
 284         uint8_t instance_id;
 285         uint16_t vendor_id;
 286         uint16_t device_id;
 287         uint16_t revision_id;
 288         uint32_t subsystem_id;
 289         uint8_t device_type;
 290         uint8_t direction;
 291         uint8_t virtual_bus_id;
 292         struct nhlt_specific_config config;
 293         uint8_t num_formats;
 294         struct nhlt_format formats[MAX_FORMATS];
 295 };
 296
 297 #define MAX_ENDPOINTS 8
 298 struct nhlt {
 299         uint8_t num_endpoints;
 300         struct nhlt_endpoint endpoints[MAX_ENDPOINTS];
 301         uint8_t current_instance_id[NHLT_MAX_LINK_TYPES];
 302 };
 303
 304 struct nhlt_tdm_config {
 305         uint8_t virtual_slot;
 306         uint8_t config_type;
 307 };
 308
 309 enum {
 310         NHLT_TDM_BASIC,
 311         NHLT_TDM_MIC_ARRAY,
 312 };
 313
 314 struct nhlt_dmic_array_config {
 315         struct nhlt_tdm_config tdm_config;
 316         uint8_t array_type;
 317 };
 318
 319 /*
 320  * Microphone array definitions may be found here:
 321  * https://msdn.microsoft.com/en-us/library/windows/hardware/dn613960%28v=vs.85%29.aspx
 322  */
 323 enum {
 324         NHLT_MIC_ARRAY_2CH_SMALL = 0xa,
 325         NHLT_MIC_ARRAY_2CH_BIG = 0xb,
 326         NHLT_MIC_ARRAY_4CH_1ST_GEOM = 0xc,
 327         NHLT_MIC_ARRAY_4CH_L_SHAPED = 0xd,
 328         NHLT_MIC_ARRAY_4CH_2ND_GEOM = 0xe,
 329         NHLT_MIC_ARRAY_VENDOR_DEFINED = 0xf,
 330 };
 331
 332 #endif