Received-SPF: pass (google.com: domain of linux-wireless+bounces-225-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Message-ID: <ad106721-343b-4449-b57c-1556c32779e7@amd.com>
Date: Wed, 29 Nov 2023 11:21:03 -0600
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v14 1/9] Documentation/driver-api: Add document about WBRF
 mechanism
Content-Language: en-US
To: Ma Jun <Jun.Ma2@amd.com>, amd-gfx@lists.freedesktop.org, lenb@kernel.org,
 hdegoede@redhat.com, johannes@sipsolutions.net, davem@davemloft.net,
 edumazet@google.com, kuba@kernel.org, pabeni@redhat.com,
 alexander.deucher@amd.com, Lijo.Lazar@amd.com, netdev@vger.kernel.org,
 linux-wireless@vger.kernel.org, linux-kernel@vger.kernel.org,
 linux-doc@vger.kernel.org, platform-driver-x86@vger.kernel.org
Cc: majun@amd.com
References: <20231129091348.3972539-1-Jun.Ma2@amd.com>
 <20231129091348.3972539-2-Jun.Ma2@amd.com>
From: Mario Limonciello <mario.limonciello@amd.com>
In-Reply-To: <20231129091348.3972539-2-Jun.Ma2@amd.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?THV1OGZCSmNWSTFhNkwyVUJwMENJQ29MQlNRWXVERk4yQVVsQkJqTW5YRVZz?=
 =?utf-8?B?bWdvRWdYRldzem5iMWRQNStwbDMwd243WUhVcnZ1UElHQlpTblJDaUZac1VY?=
 =?utf-8?B?OTZjbzhCZEJGZzFmTFQ1K1FjSytoVzhQTlZTbHFuSnl6M0dudDlobDVpVmFC?=
 =?utf-8?B?dDFKSklLSjZqazR4bGJ0Sy9hanBMMnVMWS9YT2lKSS9NL2IwSGZIUUp2OFg1?=
 =?utf-8?B?ZDlNYmd6aTJZTjh5MDZnOWdFWUdLWWVCakxhU2ZKekNGbmduMHdxbUpMMnZ0?=
 =?utf-8?B?Q3RsTEkvS29JUFRUTENWQzZ4MTdLZWxDZDV6d1A4SjRLSlJhVFZhdE1kRDZp?=
 =?utf-8?B?MThINVhWaGxPOVI5Y1lSSWNnTjgxSVdZQk4xS2Q4VGQ2SDEwZE92alVYaDJm?=
 =?utf-8?B?R09haHVwTjhINjU5Wi9QK2I3a1FYVjdiSXJiUmNRQzQ4SHNxTFVFWVlQaldZ?=
 =?utf-8?B?N0Z3ckRXamRibmU2MlZtZTdldXI3OCtsVVd0OXdlOVZTTFQ0UEFmQU5RZkJD?=
 =?utf-8?B?NWF4bTQyNkRLTkNWNDVhYSszTUtQaDF5dEYwcDVtc09HR0xtZHMvd0IyaG9Y?=
 =?utf-8?B?TnlnVUVzM2UrM0VaQkF3UVZPcVZ1cHBWMVlBWWpnZ1NNVVZ5Q0VSeDAvRzdT?=
 =?utf-8?B?NkttSTcwOVZ4MWtUWkM1NkFaQ0RhRVRNMDVvTm5YbVNzYW1qVE51SlBLYkhj?=
 =?utf-8?B?QnhxWTEzbUlDSUJ3YWgxSG4raFZ4c3ZlRE1zeG1haVk4ZXZVbFpZaFpvZCtq?=
 =?utf-8?B?NjczempxMzFJaDB3Y3VLaXRhVWNZWGREZ0FoRkxDTmRMejdybFNDTU5PM0F0?=
 =?utf-8?B?SmZxYzZlQ01VQmRDNUo2b0p1d2tHcjVPSnpUek10aC93dkJSL1BydzlxM3Ur?=
 =?utf-8?B?ZVFqZlFqaG1IcDlFeGhkK08yVmRPN2cyLy93Z1JESS9FdGxFNnJsa1RtUlVs?=
 =?utf-8?B?UjlCbmhMTjlvNXk3OHJBcDdIS0I4ZWUxZ3g1MDlKQmI3VGlCZnBITkd2SlBt?=
 =?utf-8?B?VDV4V3FmSGVNb05CK3U5Zy9CTm9ZT3Q2NUw5dWVCNWhxdlJ2S0VDOW1GUmJl?=
 =?utf-8?B?NFhUN1F1bnlNQmxvV2Z6R2lqMnljRFBpdUtKS0JhbEUzT3JtaFA1YXhZWmQy?=
 =?utf-8?B?ZWdDYXYyVGxLMFFnbEVpZUVYRnFxdjFSNU92TlpWQzZwbjBhQ0Q3VTRFTzB4?=
 =?utf-8?B?TDlNTWFDWnV0STFrY2hCQXM2UFFMMS93N1hqcGRqZEYwZU45WEUxWXRINFd4?=
 =?utf-8?B?NURlOUdwRGprUXlmMDFwYWEwVTltMFIrcktTdnpzT3BVc1ZOSEtLZ2E4ZHJ4?=
 =?utf-8?B?UzNDQWkrSWRHWmlqeTFqY3cyaHU5Nm1mZzdacCs3dGZ5cFlUTlphQUJheEM2?=
 =?utf-8?B?M28wK2VuRE8vOGJ4QnZtOGlqRnZIOVlwYWZhR0VoaUZDOUIxV0ZZVmtBQisx?=
 =?utf-8?B?QWQ5TVplQnpsT2xnUzRSeUdHR2tYSXRnZEpmc2lwenVKTkxtb0RITVVSQlRr?=
 =?utf-8?B?OHovWnpPdmRzNWdXdTk3dExXTDYvSDRzeWdRLzZTU1VsWnNCTHgzRENPK3JP?=
 =?utf-8?B?YmlMV3doQkx5NWVFOEtCcmFuaXZGaVU3alg0TXl4SUVHeHp0Z0RJOXBRaGdB?=
 =?utf-8?B?TnJLKy95VHptM29wNXQzUUFGWm9yTnZnSEJrME9HaStYa01tcTAxY2Z6cU5L?=
 =?utf-8?B?OEdHdUQ1ZzJqZ3E3QkFMYS9FaUl2STBKM1JiWFFKWkwrUm5wUkl5ejFnZjVK?=
 =?utf-8?B?UnJCdHdjWEJZN3VBdkJadStIZWlRd3BpTWdnQk5mdDNFRm82WVZTNXdyL0FD?=
 =?utf-8?B?UzZsNEdubjdwQzBsd2crMlZySnViSmp6NnpJOUhtdW5sb0JaaGYxUjAxb2tF?=
 =?utf-8?B?dXhheHAwVkxmUXFEMmYzdXRSN3dqKzRKSFVyWmRKc2xVWUJLQW5lVng2dzc0?=
 =?utf-8?B?bldIK3VIaW9yMzRjcmxrcnp1bVRpdi9UMW9rQXpQamwzTEtEM01jWm1nRUNR?=
 =?utf-8?B?RURmZXU2cUowSEl1ejF3MVJXRjhjUUtqaVFuYTB1R293MmQrdlJIWUx3MzBU?=
 =?utf-8?B?TXRDamZiRi9GdFN6dmRsNUxydEhyRUpBSHgxQnd5bzYvNXpuRkREQW5rYmxl?=
 =?utf-8?Q?WPG9q14w6/VQSdwwIxhzkK8AW?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 0791686f-7ac6-444a-1b77-08dbf0ff92ff
X-MS-Exchange-CrossTenant-AuthSource: MN0PR12MB6101.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 29 Nov 2023 17:21:07.7706
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: B698ZknZjcBPawcUhDn7E5bTeyZpLefCeGiTSf7+JVn9Vs3WQGVWxTwDqWttcDc8rnbbUam0rvcF2SJRmPiptg==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR12MB7487

On 11/29/2023 03:13, Ma Jun wrote:
> 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>

> 
> --
> v14:
> - Fix the format issue (IIpo Jarvinen)
> ---
>   Documentation/driver-api/wbrf.rst | 78 +++++++++++++++++++++++++++++++
>   1 file changed, 78 insertions(+)
>   create mode 100644 Documentation/driver-api/wbrf.rst
> 
> 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.