* README file for Discretix CC Low-Level Integration Tester module

1. Introduction
   The dx_cc_ll_test module allows verifying basic low level functionality of
   the Discretix CC (public) core from within a Linux environment.
   This module verifies 3 main facilities:
   1. CC I/O mapped registers access. This includes HW and ROM version verification.
   2. AXI master functionality.
   3. Interrupt request line integration.
   It is recommended to repeat this test several times (3 or more) since some
   error cases are dependent on the data cache status, thus may pass randomly
   even in case of an integration problem.

2. Installation
   0. Make sure that your target platform boots with DTB (device tree configuration)
      that includes dx_cc44p compatible device
   1. Verify CC resources constants definitions in cc_ll_test.h to match your platform, primarily:
      HW_VERSION and ROM_VERSION
   2. Build the test as directed in the FW integration guide.
	export KERNEL_DIR=/path/to/linux/kernel/sources
	export CROSS_COMPILE=your_arm_toolchain_prefix  # (e.g., arm-linux-gnueabi- )
	cd host/src/cc_ll_test
	make
   3. Copy the built kernel module - dx_cc_ll_test.ko - to the respective modules path
      on your platform, e.g., /lib/modules/3.8.0-foo/
   4. Run "depmod" on your target to update modules.dep with this new kernel module

3. Test execution
   Load the test kernel module: modprobe dx_cc_ll_test
   The command line prompt would stall until the tests execution is completed.
   When execution completed the test module should be unloaded before being able
   to repeat the test (modprobe -r dx_cc_ll_test).
   All the test execution is logged in the system kernel log, i.e.,
   may be output to platform's console or to syslog (/vat/log/syslog) file if kernel logging daemon is enabled.
   The basic logging level reports of test progress and its final results.
   In case of error the specific case error information is logged, too.
   Test log example:
	DxCC LLtest: Discretix CC low-level tester module loaded.                                                                      
	DxCC LLtest: Tester start:                                                                                                     
	DxCC LLtest: Cache params set to 0x00000000                                                                                    
	DxCC LLtest: Using default dma_ops.                                                                                            
	DxCC LLtest: 0. size=4096  din_offset=64  dout_offset=64                                                                       
	DxCC LLtest: 1. size=256  din_offset=64  dout_offset=64                                                                        
	DxCC LLtest: 2. size=64  din_offset=64  dout_offset=64                                                                         
	...
	DxCC LLtest: 285. size=4  din_offset=1  dout_offset=1
	DxCC LLtest: 286. size=2  din_offset=1  dout_offset=1
	DxCC LLtest: 287. size=1  din_offset=1  dout_offset=1
	DxCC LLtest: All (288) tests passed.

4. Optional test options:
   There are a few kernel module parameters that may be optionally provided to
   override the default values.
	dma_coherent_ops:	1 for arm_coherent_dma_ops (HCCC mode), 0 (default) for arm_dma_ops (SCCC mode)
				* NOTE: You must reboot Linux before changing this option!
					Selecting different DMA operations for subsequent tests
					without rebooting may result in test failure.
	cache_params:		Discretix DMA master AR/AW-cache parameters.
				Should be 0 if dma_coherent_ops==0 and !0 if dma_coherent_ops==1.
	test_idx:		Test case selection: Index of test case to run. Default: (-1) all tests.
				Useful when specific test case needs to be debugged.
	test_log_level:		Test logging level:
				0 - just errors, 1 - per case status (default), 2 - detailed logging

5. Results analysis:
   In any case of failure of some of the test cases, one should check the test
   logs as detailed above. In addition, in case of failure of specific test cases
   one may use the "test_idx" module parameter to re-run just that specific case.
   In case one contacts Discretix Professional Services for support, he/she should
   include the system log output when running with "test_log_level=2".
   The following information provides some details on common failures.
   1. Device identification:
      The CC integration test basically verifies correct mapping of its registers space
      before starting actual testing.
      In case no message appears on the system logs after loading the kernel module,
      verify that your kernel logging actually works. The system log must include at
      least the kernel loading log message:
         DxCC LLtest: Discretix CC low-level tester module loaded.
      If the above message appears in the logs but nothing more, this may imply
      that the CC device is not identified as a platform device. In systems that
      use device tree configuration (CONFIG_OF) this may imply problem with the
      DTB file. Either the CC device is missing from the platform device tree, or
      it may exist but does not include correct compatibility attribute:
         compatible = "dx,cc44p";
      When this issue is fixed, one should see the following log message that
      indicates the device was identified and triggered the "probe" entry point:
         DxCC LLtest: Tester start:
    2. Registers access and version verification:
       Following the device identification actual access is performed to registers
       with known/expected values. This includes:
       SIGNATURE - Expected known device identification value. If that value is incorrect it implies
                   that the CC registers space is not visible at address given by
		   the platform configuration. Check the "reg" attribute of the
		   device in the device tree configuration.
       HW Version - Expected Discretix CC core HW version, as defined in cc_ll_test.h
       ROM Version- Expected CC ROM version, as defined in cc_ll_test.h
       In case of mismatch a respective error message would appear in the logs.
    3. After CC registers access is verified the main test cases are executed.
       All the listed test cases perform DMA operation from one memory buffer to
       another. The buffers are of different sizes and located at different page
       offsets. For example:
          DxCC LLtest: 25. size=256  din_offset=4  dout_offset=64
       In this test case example, DMA of 256 bytes at page offset of 4 B for the
       input buffer and page offset of 64 B for the output buffer.
       The test expects an operation completion interrupt as a result of this operation.
       If the interrupt is not witnessed within 2 seconds, we assume there is a 
       problem with the IRQ line integration. This error is reported as
       "Timeout waiting for AXI completion interrupt" and completion is checked
       manually.
       Upon DMA completion, the output buffer is verified to match the expected
       output data (i.e., to match DMA input data). In addition, it verifies that
       only the output buffer was written and that there was no "leak" outside of
       it (typical to bad byte-enables routing or cache coherency problems).
