diff mbox series

[v15,1/9] Documentation/driver-api: Add document about WBRF mechanism

Message ID 20231206072947.1331729-2-Jun.Ma2@amd.com
State Superseded
Headers show
Series Enable Wifi RFI interference mitigation feature support | expand

Commit Message

Ma Jun Dec. 6, 2023, 7:29 a.m. UTC 
Add documentation about AMD's Wifi band RFI mitigation (WBRF) mechanism
explaining the theory and how it is used.

Signed-off-by: Ma Jun <Jun.Ma2@amd.com>
Reviewed-by: Hans de Goede <hdegoede@redhat.com>
Reviewed-by: Mario Limonciello <mario.limonciello@amd.com>
---
 Documentation/driver-api/wbrf.rst | 78 +++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 Documentation/driver-api/wbrf.rst

Comments

kernel test robot Dec. 7, 2023, 12:01 p.m. UTC | #1 
Hi Ma,

kernel test robot noticed the following build warnings:

[auto build test WARNING on linus/master]
[also build test WARNING on v6.7-rc4 next-20231207]
[cannot apply to drm-misc/drm-misc-next wireless-next/main wireless/main]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Ma-Jun/Documentation-driver-api-Add-document-about-WBRF-mechanism/20231206-153327
base:   linus/master
patch link:    https://lore.kernel.org/r/20231206072947.1331729-2-Jun.Ma2%40amd.com
patch subject: [PATCH v15 1/9] Documentation/driver-api: Add document about WBRF mechanism
reproduce: (https://download.01.org/0day-ci/archive/20231207/202312071941.JXQXsK1C-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202312071941.JXQXsK1C-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Documentation/driver-api/wbrf.rst:28: WARNING: Unexpected indentation.
>> Documentation/driver-api/wbrf.rst:61: WARNING: Block quote ends without a blank line; unexpected unindent.
>> Documentation/driver-api/wbrf.rst: WARNING: document isn't included in any toctree

vim +28 Documentation/driver-api/wbrf.rst

    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
    29	           mitigate the 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
diff mbox series

Patch

diff --git a/Documentation/driver-api/wbrf.rst b/Documentation/driver-api/wbrf.rst
new file mode 100644
index 000000000000..12793bb1abce
--- /dev/null
+++ b/Documentation/driver-api/wbrf.rst
@@ -0,0 +1,78 @@ 
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+=================================
+WBRF - Wifi Band RFI Mitigations
+=================================
+
+Due to electrical and mechanical constraints in certain platform designs
+there may be likely interference of relatively high-powered harmonics of
+the GPU memory clocks with local radio module frequency bands used by
+certain Wifi bands.
+
+To mitigate possible RFI interference producers can advertise the
+frequencies in use and consumers can use this information to avoid using
+these frequencies for sensitive features.
+
+When a platform is known to have this issue with any contained devices,
+the platform designer will advertise the availability of this feature via
+ACPI devices with a device specific method (_DSM).
+* Producers with this _DSM will be able to advertise the frequencies in use.
+* Consumers with this _DSM will be able to register for notifications of
+frequencies in use.
+
+Some general terms
+==================
+
+Producer: such component who can produce high-powered radio frequency
+Consumer: such component who can adjust its in-use frequency in
+           response to the radio frequencies of other components to
+           mitigate the possible RFI.
+
+To make the mechanism function, those producers should notify active use
+of their particular frequencies so that other consumers can make relative
+internal adjustments as necessary to avoid this resonance.
+
+ACPI interface
+==============
+
+Although initially used by for wifi + dGPU use cases, the ACPI interface
+can be scaled to any type of device that a platform designer discovers
+can cause interference.
+
+The GUID used for the _DSM is 7B7656CF-DC3D-4C1C-83E9-66E721DE3070.
+
+3 functions are available in this _DSM:
+
+* 0: discover # of functions available
+* 1: record RF bands in use
+* 2: retrieve RF bands in use
+
+Driver programming interface
+============================
+
+.. kernel-doc:: drivers/platform/x86/amd/wbrf.c
+
+Sample Usage
+=============
+
+The expected flow for the producers:
+1. During probe, call `acpi_amd_wbrf_supported_producer` to check if WBRF
+   can be enabled for the device.
+2. On using some frequency band, call `acpi_amd_wbrf_add_remove` with 'add'
+   param to get other consumers properly notified.
+3. Or on stopping using some frequency band, call
+   `acpi_amd_wbrf_add_remove` with 'remove' param to get other consumers notified.
+
+The expected flow for the consumers:
+1. During probe, call `acpi_amd_wbrf_supported_consumer` to check if WBRF
+   can be enabled for the device.
+2. Call `amd_wbrf_register_notifier` to register for notification
+   of frequency band change(add or remove) from other producers.
+3. Call the `amd_wbrf_retrieve_freq_band` initally to retrieve
+   current active frequency bands considering some producers may broadcast
+   such information before the consumer is up.
+4. On receiving a notification for frequency band change, run
+   `amd_wbrf_retrieve_freq_band` again to retrieve the latest
+   active frequency bands.
+5. During driver cleanup, call `amd_wbrf_unregister_notifier` to
+   unregister the notifier.