gpu: nvgpu: unit: add SWUTS doc for nvgpu_sgt

Add the doxygen documentation for the SWUTS for the nvgpu_sgt unit test.

JIRA NVGPU-3943

Change-Id: Ic13e4227718f0417f8f2053feda21f4db00748bb
Signed-off-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/2199001
Reviewed-by: svc-mobile-coverity <svc-mobile-coverity@nvidia.com>
Reviewed-by: svc-mobile-misra <svc-mobile-misra@nvidia.com>
GVS: Gerrit_Virtual_Submit
Reviewed-by: Alex Waterman <alexw@nvidia.com>
Reviewed-by: Deepak Nibade <dnibade@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>

userspace/SWUTS.h

@@ -36,6 +36,7 @@
  *   - @ref SWUTS-mm-allocators-bitmap-allocator
  *   - @ref SWUTS-mm-allocators-buddy-allocator
  *   - @ref SWUTS-mm-nvgpu-mem
+ *   - @ref SWUTS-mm-nvgpu-sgt
  *   - @ref SWUTS-mm-vm
  *   - @ref SWUTS-fuse
  *   - @ref SWUTS-posix-sizes

userspace/SWUTS.sources

@@ -8,6 +8,7 @@ INPUT += ../../../userspace/units/interface/atomic/atomic.h
 INPUT += ../../../userspace/units/mm/allocators/bitmap_allocator/bitmap_allocator.h
 INPUT += ../../../userspace/units/mm/allocators/buddy_allocator/buddy_allocator.h
 INPUT += ../../../userspace/units/mm/nvgpu_mem/nvgpu_mem.h
+INPUT += ../../../userspace/units/mm/nvgpu_sgt/nvgpu_sgt.h
 INPUT += ../../../userspace/units/mm/vm/vm.h
 INPUT += ../../../userspace/units/posix/sizes/posix-sizes.h
 INPUT += ../../../userspace/units/posix/thread/posix-thread.h

userspace/units/mm/nvgpu_sgt/nvgpu_sgt.c

@@ -29,6 +29,8 @@
 #include <nvgpu/sizes.h>
 #include <os/posix/os_posix.h>
 
+#include "nvgpu_sgt.h"
+
 /* nvgpu_sgt_ops overrides for basic api testing */
 #define EXPECTED_U64 0x123456789ABCDEF0ULL
 static u64 ops_sgl_gpu_addr(struct gk20a *g, void *sgl,
@@ -54,20 +56,7 @@ static struct nvgpu_sgt_ops nvgpu_sgt_ops = {
 	.sgl_ipa_to_pa = ops_sgl_ipa_to_pa,
 };
 
-/*
+int test_nvgpu_sgt_basic_apis(struct unit_module *m, struct gk20a *g,
- * Test: test_nvgpu_sgt_basic_apis
- * Tests for the simple APIs provided by nvgpu_sgt unit
- * APIs tested:
- *      nvgpu_sgt_create_from_mem
- *      nvgpu_sgt_get_dma
- *      nvgpu_sgt_get_phys
- *      nvgpu_sgt_iommuable
- *      nvgpu_sgt_get_gpu_addr
- *      nvgpu_sgt_get_ipa
- *      nvgpu_sgt_ipa_to_pa
- *      nvgpu_sgt_free
- */
-static int test_nvgpu_sgt_basic_apis(struct unit_module *m, struct gk20a *g,
 				     void *args)
 {
 	int ret = UNIT_SUCCESS;
@@ -163,12 +152,7 @@ end:
 	return ret;
 }
 
-/*
+int test_nvgpu_sgt_get_next(struct unit_module *m, struct gk20a *g,
- * Test: test_nvgpu_sgt_get_next
- * Tests test_nvgpu_sgt_get_next API by building sgl's and verifying
- * correct pointers returned by calling the API
- */
-static int test_nvgpu_sgt_get_next(struct unit_module *m, struct gk20a *g,
 				   void *args)
 {
 	int ret = UNIT_SUCCESS;
@@ -344,12 +328,7 @@ static int test_table_nvgpu_sgt_alignment_non_iommu(struct unit_module *m,
 	return ret;
 }
 
-/*
+int test_nvgpu_sgt_alignment_non_iommu(struct unit_module *m,
- * Test: test_nvgpu_sgt_alignment_non_iommu
- * Walks table above to test a variety of different sgl's to test alignment
- * API calculates correctly when there is no IOMMU.
- */
-static int test_nvgpu_sgt_alignment_non_iommu(struct unit_module *m,
 					      struct gk20a *g, void *args)
 {
 	int ret = UNIT_SUCCESS;
@@ -371,17 +350,7 @@ static int test_nvgpu_sgt_alignment_non_iommu(struct unit_module *m,
 	return ret;
 }
 
-/*
+int test_nvgpu_sgt_alignment_with_iommu(struct unit_module *m,
- * Test the alignment API for the case where there is an IOMMU
- * For this case, we need:
- *  1. an IOMMU
- *  2. the sgt to be marked IOMMU'able
- *  3. DMA addr != 0
- * So, we check we don't use the IOMMU code path by not having these right.
- * To make sure we didn't we make the DMA address and size different.
- * Because if it's IOMMU'able the alignment is based on the DMA address.
- */
-static int test_nvgpu_sgt_alignment_with_iommu(struct unit_module *m,
 					       struct gk20a *g, void *args)
 {
 	int ret = UNIT_SUCCESS;

userspace/units/mm/nvgpu_sgt/nvgpu_sgt.h

@@ -0,0 +1,154 @@
+/*
+ * Copyright (c) 2019, NVIDIA CORPORATION.  All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef UNIT_NVGPU_SGT_H
+#define UNIT_NVGPU_SGT_H
+
+struct gk20a;
+struct unit_module;
+
+/** @addtogroup SWUTS-mm-nvgpu-sgt
+ *  @{
+ *
+ * Software Unit Test Specification for mm-nvgpu-sgt
+ */
+
+/**
+ * Test specification for: test_nvgpu_sgt_basic_apis
+ *
+ * Description: Tests for the simple APIs provided by nvgpu_sgt unit.
+ *
+ * Test Type: Feature based
+ *
+ * Input: None
+ *
+ * Steps:
+ * - Test nvgpu_sgt_create_from_mem.
+ *   - Create an nvgpu_mem object from an sgl.
+ *   - Set VA for nvgpu_mem object.
+ *   - Pass nvgpu_mem object to nvgpu_sgt_create_from_mem(), and verify pointer
+ *     returned.
+ * - Test nvgpu_sgt_get_phys by checking the physical address in sgt above is
+ *   set to the VA set in the nvgpu_mem.
+ * - Test nvgpu_sgt_get_dma by passing in the sgl from sgt above, and verify
+ *   correct DMA address is returned.
+ * - Test nvgpu_sgt_iommuable.
+ *   - Call nvgpu_sgt_iommuable() and verify returned value maches what is set
+ *     posix struct member mm_sgt_is_iommuable.
+ *   - Override the nvgpu_sgt_ops HAL with the sgt_iommuable op set to NULL.
+ *   - Call nvgpu_sgt_iommuable() and verify false is returned.
+ * - Using an overridden HAL op to return an expected value, call
+ *   nvgpu_sgt_get_gpu_addr() and verify the returned value is correct.
+ * - Using an overridden HAL op to return an expected value, call
+ *   nvgpu_sgt_get_ipa() and verify the returned value is correct.
+ * - Using an overridden HAL op to return an expected value, call
+ *   nvgpu_sgt_ipa_to_pa() and verify the returned value is correct.
+ * - Call nvgpu_sgt_free(), passing a NULL pointer for the sgt to test the error
+ *   checking path.
+ * - Call nvgpu_sgt_free(), passing the sgt used previously in this test.
+ * - Restore default nvgpu_sgt_ops HALs.
+ *
+ * Output: Returns SUCCESS if the steps above were executed successfully. FAIL
+ * otherwise.
+ */
+int test_nvgpu_sgt_basic_apis(struct unit_module *m, struct gk20a *g,
+				     void *args);
+
+/**
+ * Test specification for: test_nvgpu_sgt_get_next
+ *
+ * Description: Tests test_nvgpu_sgt_get_next API by building sgl's and
+ *              verifying correct pointers returned by calling the API.
+ *
+ * Test Type: Feature based
+ *
+ * Input: None
+ *
+ * Steps:
+ * - Create a table of sgl's.
+ * - Create an sgt from the list of sgl's.
+ * - Call nvgpu_sgt_get_next() in a loop and verify it returns the list above
+ *   in the correct order and the final element returned is NULL.
+ *
+ * Output: Returns SUCCESS if the steps above were executed successfully. FAIL
+ * otherwise.
+ */
+int test_nvgpu_sgt_get_next(struct unit_module *m, struct gk20a *g,
+				   void *args);
+
+/**
+ * Test specification for: test_nvgpu_sgt_alignment_non_iommu
+ *
+ * Description: Test the alignment API for the case where there is no IOMMU.
+ *
+ * Test Type: Feature based
+ *
+ * Input: Static sgt_align_test_array table of alignment combinations.
+ *
+ * Steps:
+ * - Loop through the table of test alignment combinations. For each config:
+ *   - Create an sgt.
+ *   - Call nvgpu_sgt_alignment() and verify the expected alignment is returned.
+ *   - Free the sgt.
+ *
+ * Output: Returns SUCCESS if the steps above were executed successfully. FAIL
+ * otherwise.
+ */
+/*
+ * Test: test_nvgpu_sgt_alignment_non_iommu
+ * Walks table above to test a variety of different sgl's to test alignment
+ * API calculates correctly when there is no IOMMU.
+ */
+int test_nvgpu_sgt_alignment_non_iommu(struct unit_module *m,
+					      struct gk20a *g, void *args);
+
+/**
+ * Test specification for: test_nvgpu_sgt_alignment_with_iommu
+ *
+ * Description: Test the alignment API for the case where there is an IOMMU.
+ *
+ * Test Type: Feature based
+ *
+ * Input: None
+ *
+ * Steps:
+ * - Create an sgt.
+ * - Test the code paths for not using the IOMMU for alignment.
+ *   - Cycle through all combinations of the following conditions that gate
+ *     using the IOMMU address:
+ *     - IOMMU enabled.
+ *     - The sgt being iommuable.
+ *     - The sgl's DMA address not equal 0.
+ *   - For each case, verify nvgpu_set_alignment() does not return the DMA
+ *     address of the sgl (the IOMMU address).
+ * - Test when the IOMMU is enabled, the sgt is iommuable, and the sgl's DMA
+ *   address is not 0, that nvgpu_set_alignment() does return the sgl's DMA
+ *   address for the alignment.
+ * - Free the sgt.
+ *
+ * Output: Returns SUCCESS if the steps above were executed successfully. FAIL
+ * otherwise.
+ */
+int test_nvgpu_sgt_alignment_with_iommu(struct unit_module *m,
+					       struct gk20a *g, void *args);
+
+#endif /* UNIT_NVGPU_SGT_H */