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