Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <6e63dd2b-de01-c707-cf4b-33eb7d1eb0c4@amd.com>
Date:   Thu, 10 Mar 2022 09:47:36 +0530
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101
 Thunderbird/91.4.0
Subject: Re: [PATCH v2 1/2] Documentation: x86: Add documenation for AMD IOMMU
Content-Language: en-US
To:     Alex Deucher <alexander.deucher@amd.com>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        corbet@lwn.net, hpa@zytor.com, x86@kernel.org,
        dave.hansen@linux.intel.com, bp@alien8.de, mingo@redhat.com,
        tglx@linutronix.de, joro@8bytes.org, suravee.suthikulpanit@amd.com,
        will@kernel.org, iommu@lists.linux-foundation.org,
        robin.murphy@arm.com
References: <20220309175805.1298503-1-alexander.deucher@amd.com>
From:   Vasant Hegde <vasant.hegde@amd.com>
In-Reply-To: <20220309175805.1298503-1-alexander.deucher@amd.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?N1R4b0lpd292dG9kR1hTYjhhcEVZY1FjcTh2MzY1a0lEeWQzSjg2dGpScHA3?=
 =?utf-8?B?NHRXWWlOWWh5aVlLYnlHQ1JydGNOcksxNUVobHRJb1lQS2F4cng2RUFIcjlR?=
 =?utf-8?B?SUV1Z0wrbmp2OW9CcUVJRjMrNXZnZDdYR3NJSTJGMUNJMTdwYlVLWCtSZTcv?=
 =?utf-8?B?dXVtRnlhK1RrY1AxczBIMDFWV2g1MjZyR2NSZFRJb3pwU0Y2NzVFMUlpRzVk?=
 =?utf-8?B?Z25MY08zaDF6YXgrbWJ5SXZLL29BdU5hVFhWQjdPWHJnVzkvbmV3OGpxZFFl?=
 =?utf-8?B?dXBKaUxjYUZ2QXNRTThTWDVKbEhXRWZBY0lDVUovYUQvYyt3cG1xN3ZtZEpl?=
 =?utf-8?B?WkZUaGFhTjVJQURvVHk1Mk56WVhjQzNNSi9hVm5TWVVKc1ZUWm03QTRORnZC?=
 =?utf-8?B?V3g3TGsxSGU5Tm56M0N3Y3huZXErbkVtOEJyMHpNZU5HbHN6WTU2L0themxX?=
 =?utf-8?B?MVZwUnRvOFpzR0NoK055aEg3NU1OaUlHeUJ0RXhQcm5YbVpKU2k5MkZtUXhE?=
 =?utf-8?B?K05NYzVPZklta2tqRU1ieU5WZEZBOHM1dDNHcVJEM01IbmhyNlQ1QWhLWVNK?=
 =?utf-8?B?K0VQVGNyaVNGbHE0QXhTd3lCVitvbDR3OUl0eTN0SlpKN0NYWThRSlJBZEdF?=
 =?utf-8?B?UXFUM0t6UFFjOXZpTDlSajJUVHpjOEhJSzNEZXZhSnJna0ZjYU95bEtmS2th?=
 =?utf-8?B?cWwyVzc1S3d1N3Axd055eU5scFRoVWNVQWJMQS9SY29VWGFyUlAwTWVWTXZD?=
 =?utf-8?B?UnphZENjbDFuU0RjbCtWVHlrNU1ETDZpSEUydk5iOC9KaVZhbUdNdHhhZGNv?=
 =?utf-8?B?VTdSTFZvSDNFOHpWNVNaMHhLTVc5NmtSZXl5LzAyLzVnWE9UTUpvd2xweVRm?=
 =?utf-8?B?dnZ2cktVd2NkMnRIZGxWdHF2ekxEbjgrZ08vVVlGeUppaDdwMHdqYUU0NHpP?=
 =?utf-8?B?WDJiUWV6R0xvbk9RU3U4Y3ZxZng4Y3haZlBuM1ZVN2dZRmhGbEdTbWswcVZv?=
 =?utf-8?B?SnR1ZjRreUJxY3RZeVVMeFRJMU1jWHFLSXg3d3hMMUhFc2d5MXk4cmNXYTh4?=
 =?utf-8?B?YXVMQk1xYU1qaDcwMkRLaDVsYzJjeUl3aU5GMk1qVDRLeFhLeXpVcHNIbmY3?=
 =?utf-8?B?NXQ4ajNhTkVnNFpoR25VR3FZUzdxbmNVeWwyM1cyUEgrVTRibEVtRU9ycWFX?=
 =?utf-8?B?YzZScnZ6aVhlMDAzS2NXK0FDb0wyOEFzdm92VVFwYVc1OTZNcjFIVkhtcnkv?=
 =?utf-8?B?M2dmUnRrRlI3YlZqT2hUaUxsdTV0eGV2SEpGQjZRQ2hFRGU4UnVqOWV5elFK?=
 =?utf-8?B?QnUrT3gvVUxtY0lVWW50VmVmcEFnUzJwMDhWeXlQblpyeE5wQUd4RmtEUkFu?=
 =?utf-8?B?ajhEbURVZU4yYnMxN0FzbksxdkNNRzFvT1BEVVgvTDB3QlIwZkErbE1xQWUx?=
 =?utf-8?B?ak9KMUtCYWl0MHNsZlBiWmdLZnJlVXlYVWhKVld0MGtNRU1hUkxabVhjNXVo?=
 =?utf-8?B?cVFhb3NJNlNIRXJyQkVXOSt0blY4eUhOMU04MTVGSlpNQTFxK3NkNkFidUhE?=
 =?utf-8?B?SW1lbXY2cGtBZTFhYzdCYUVwWXl2Y1NQZ3BKN0dJTjdETkNIbEtHdm9iU2tk?=
 =?utf-8?B?TjZsbmk1LzVUTFFoazhzWGJ4aDM4TUdxOGN5SU51K1lSaTZDaVo3TFErNkFM?=
 =?utf-8?B?cDJ5b0VxVXpjM0hGNmlaaDdpNWZYazB2eWVBSmp0eFNSVmR5anMvaWhha21n?=
 =?utf-8?B?QTdJUitObWRJL2xUNW1OU2lQUjBCdVRONlFPZThFQ01zbGJ5dFdQeDVKWDFH?=
 =?utf-8?B?NXRtaWNTeSthUUliSHA2eStYUmFsdGdra0s1eVQ4UmZ3OXp6T3dwbWlXZDZi?=
 =?utf-8?B?VnpzbzJLWmlQLythaGFGa3A1TUNoVlBLZU5aTjh6UWppSTVqQUNrdlJXWWFC?=
 =?utf-8?B?TmhZdzQ4RVhSUHFpa2J0K2YyMHMrTGRIckVIVjE3R25IWVNNVWJRRDhyNWRP?=
 =?utf-8?B?dGR6NXBDRUlmbEhQZHhqTWs2OVdYNjFsOWtXd1NYeHdJSEp0UTYycCtIWTNx?=
 =?utf-8?B?M0xKL3JJS1psMTdBU2I3a3lmZitZeXpVMkhlZXFSZVVnWkNiNzFFRXZLclNu?=
 =?utf-8?B?aHorY0tJNWxjRHMxOUVadDJ2K2ZkRExOeC9FQUw3bm96aWxxbzBIY0NBbmRD?=
 =?utf-8?Q?wBf3tGWa43ddm6VYdtR3wiQ=3D?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 588281b1-525a-4e46-9566-08da024cf0d5
X-MS-Exchange-CrossTenant-AuthSource: DM6PR12MB2906.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 10 Mar 2022 04:17:51.2332
 (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: P0z4n0PCtBRgvzbnW5b1MDWqL6mOWFTD/JpPxWG9pWJt2BXm3eFoI92IszQjDPqZV2rpt29tB7nadGTXIzmTGA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR12MB5455
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE
        autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On 3/9/2022 11:28 PM, Alex Deucher via iommu wrote:
> Add preliminary documenation for AMD IOMMU.

s/documenation /documentation/

> 
> Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
> ---
> 
> V2: incorporate feedback from Robin to clarify IOMMU vs DMA engine (e.g.,
>     a device) and document proper DMA API.  Also correct the fact that
>     the AMD IOMMU is not limited to managing PCI devices.
> 
>  Documentation/x86/amd-iommu.rst   | 69 +++++++++++++++++++++++++++++++
>  Documentation/x86/index.rst       |  1 +
>  Documentation/x86/intel-iommu.rst |  2 +-
>  3 files changed, 71 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/x86/amd-iommu.rst
> 
> diff --git a/Documentation/x86/amd-iommu.rst b/Documentation/x86/amd-iommu.rst
> new file mode 100644
> index 000000000000..6ecc4bc8c70d
> --- /dev/null
> +++ b/Documentation/x86/amd-iommu.rst
> @@ -0,0 +1,69 @@
> +=================
> +AMD IOMMU Support
> +=================
> +
> +The architecture spec can be obtained from the below location.
> +
> +https://www.amd.com/system/files/TechDocs/48882_IOMMU.pdf
> +
> +This guide gives a quick cheat sheet for some basic understanding.
> +
> +Some Keywords
> +
> +- IVRS - I/O Virtualization Reporting Structure
> +- IVDB - I/O Virtualization Definition Block
> +- IVHD - I/O Virtualization Hardware Definition
> +- IOVA - I/O Virtual Address.
> +
> +Basic stuff
> +-----------
> +
> +ACPI enumerates and lists the different IOMMUs on the platform, and
> +device scope relationships between devices and which IOMMU controls
> +them.
> +
> +What is IVRS?
> +-------------
> +
> +The architecture defines an ACPI-compatible data structure called an I/O
> +Virtualization Reporting Structure (IVRS) that is used to convey information
> +related to I/O virtualization to system software.  The IVRS describes the
> +configuration and capabilities of the IOMMUs contained in the platform as
> +well as information about the devices that each IOMMU virtualizes.
> +
> +The IVRS provides information about the following:
> +- IOMMUs present in the platform including their capabilities and proper configuration
> +- System I/O topology relevant to each IOMMU
> +- Peripheral devices that cannot be otherwise enumerated
> +- Memory regions used by SMI/SMM, platform firmware, and platform hardware. These are
> +generally exclusion ranges to be configured by system software.
> +
> +How is IOVA generated?
> +----------------------
> +
> +Well behaved drivers call dma_map_*() calls before sending command to device
> +that needs to perform DMA. Once DMA is completed and mapping is no longer
> +required, driver performs dma_unmap_*() calls to unmap the region.
> +
> +Fault reporting
> +---------------
> +
> +When errors are reported, the IOMMU signals via an interrupt. The fault
> +reason and device that caused it with fault reason is printed on console.

May be just say "... and device cause it is printed on console."?

Rest looks good to me.

-Vasant