Documentation/driver-api/wbrf.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 =================================
   4 WBRF - Wifi Band RFI Mitigations
   5 =================================
   6
   7 Due to electrical and mechanical constraints in certain platform designs
   8 there may be likely interference of relatively high-powered harmonics of
   9 the GPU memory clocks with local radio module frequency bands used by
  10 certain Wifi bands.
  11
  12 To mitigate possible RFI interference producers can advertise the
  13 frequencies in use and consumers can use this information to avoid using
  14 these frequencies for sensitive features.
  15
  16 When a platform is known to have this issue with any contained devices,
  17 the platform designer will advertise the availability of this feature via
  18 ACPI devices with a device specific method (_DSM).
  19 * Producers with this _DSM will be able to advertise the frequencies in use.
  20 * Consumers with this _DSM will be able to register for notifications of
  21 frequencies in use.
  22
  23 Some general terms
  24 ==================
  25
  26 Producer: such component who can produce high-powered radio frequency
  27 Consumer: such component who can adjust its in-use frequency in
  28 response to the radio frequencies of other components to mitigate the
  29 possible RFI.
  30
  31 To make the mechanism function, those producers should notify active use
  32 of their particular frequencies so that other consumers can make relative
  33 internal adjustments as necessary to avoid this resonance.
  34
  35 ACPI interface
  36 ==============
  37
  38 Although initially used by for wifi + dGPU use cases, the ACPI interface
  39 can be scaled to any type of device that a platform designer discovers
  40 can cause interference.
  41
  42 The GUID used for the _DSM is 7B7656CF-DC3D-4C1C-83E9-66E721DE3070.
  43
  44 3 functions are available in this _DSM:
  45
  46 * 0: discover # of functions available
  47 * 1: record RF bands in use
  48 * 2: retrieve RF bands in use
  49
  50 Driver programming interface
  51 ============================
  52
  53 .. kernel-doc:: drivers/platform/x86/amd/wbrf.c
  54
  55 Sample Usage
  56 =============
  57
  58 The expected flow for the producers:
  59 1. During probe, call `acpi_amd_wbrf_supported_producer` to check if WBRF
  60 can be enabled for the device.
  61 2. On using some frequency band, call `acpi_amd_wbrf_add_remove` with 'add'
  62 param to get other consumers properly notified.
  63 3. Or on stopping using some frequency band, call
  64 `acpi_amd_wbrf_add_remove` with 'remove' param to get other consumers notified.
  65
  66 The expected flow for the consumers:
  67 1. During probe, call `acpi_amd_wbrf_supported_consumer` to check if WBRF
  68 can be enabled for the device.
  69 2. Call `amd_wbrf_register_notifier` to register for notification
  70 of frequency band change(add or remove) from other producers.
  71 3. Call the `amd_wbrf_retrieve_freq_band` initially to retrieve
  72 current active frequency bands considering some producers may broadcast
  73 such information before the consumer is up.
  74 4. On receiving a notification for frequency band change, run
  75 `amd_wbrf_retrieve_freq_band` again to retrieve the latest
  76 active frequency bands.
  77 5. During driver cleanup, call `amd_wbrf_unregister_notifier` to
  78 unregister the notifier.