*************************************************************************
   ____  ____
  /   /\/   /
 /___/  \  /
 \   \   \/     Copyright 2015 Xilinx, Inc. All rights reserved.
  \   \        This file contains confidential and proprietary
  /   /        information of Xilinx, Inc. and is protected under U.S.
 /___/   /\    and international copyright and other intellectual
 \   \  /  \   property laws.
  \___\/\___\

*************************************************************************

Vendor: Xilinx
Current README.txt Version: 1.1
Date Last Modified:  14APR2016
Date Created: 28MAR2016

Associated Filename: rdf0369-zc702-zvik-videocmd-motiondetect-sdsoc-2015-4.zip
Associated Document: UG925 - Zynq-7000 ZC702 Evaluation Kit User Guide
                     http://www.wiki.xilinx.com/Zynq+Base+TRD+2015.4
                     US873 - Zynq Concepts, Tools and Techniques
                     UG798 - Xilinx Design Tools: Installation and 
                             Licensing Guide
                     UG850 - ZC702 Evaluation Board User Guide
                     UG1028 - SDSoC Environment User Guide
Supported Device(s): XC7Z020-1CLG484

*************************************************************************

Disclaimer:

      This disclaimer is not a license and does not grant any rights to
      the materials distributed herewith. Except as otherwise provided in
      a valid license issued to you by Xilinx, and to the maximum extent
      permitted by applicable law: (1) THESE MATERIALS ARE MADE AVAILABLE
      "AS IS" AND WITH ALL FAULTS, AND XILINX HEREBY DISCLAIMS ALL
      WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, OR STATUTORY,
      INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
      NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and
      (2) Xilinx shall not be liable (whether in contract or tort,
      including negligence, or under any other theory of liability) for
      any loss or damage of any kind or nature related to, arising under
      or in connection with these materials, including for any direct, or
      any indirect, special, incidental, or consequential loss or damage
      (including loss of data, profits, goodwill, or any type of loss or
      damage suffered as a result of any action brought by a third party)
      even if such damage or loss was reasonably foreseeable or Xilinx
      had been advised of the possibility of the same.

Critical Applications:

      Xilinx products are not designed or intended to be fail-safe, or
      for use in any application requiring fail-safe performance, such as
      life-support or safety devices or systems, Class III medical
      devices, nuclear facilities, applications related to the deployment
      of airbags, or any other applications that could lead to death,
      personal injury, or severe property or environmental damage
      (individually and collectively, "Critical Applications"). Customer
      assumes the sole risk and liability of any use of Xilinx products
      in Critical Applications, subject only to applicable laws and
      regulations governing limitations on product liability.

THIS COPYRIGHT NOTICE AND DISCLAIMER MUST BE RETAINED AS PART OF THIS
FILE AT ALL TIMES.

*************************************************************************

*************************************************************************

The applications shipped with this reference design include Linux kernel
header files and are not considered a "derivative work" for the purposes
of the GPL.

*************************************************************************
This readme file contains these sections:

1. REVISION HISTORY
2. OVERVIEW
3. SOFTWARE TOOLS AND SYSTEM REQUIREMENTS
4. DESIGN FILE HIERARCHY
5. INSTALLATION AND OPERATING INSTRUCTIONS
6. OTHER INFORMATION
7. SUPPORT


=======================
1. REVISION HISTORY
=======================


            Readme
Date        Version      Revision Description
=========================================================================
28SEP2015   1.0          Initial Xilinx release.
14APR2016   1.1          Single hardware platform for 2 sample applications
                         (video_cmd, motion_detect)
=========================================================================


=======================
2. OVERVIEW
=======================

  MOTION DETECT APPLICATION:
  --------------------------
  The Motion Detect is an embedded video processing application designed to
  showcase various features and capabilities of Zynq Z-7020 All Programmable 
  SoC (AP SoC) device for the embedded domain. The Motion Detect consists of 
  two elements: The Zynq-7000 AP SoC Processing System (PS) and a video 
  processing pipeline implemented in Programmable Logic (PL). The AP SoC allows
  the user to implement a video processing algorithm that performs motion 
  detection on an image (Sobel filter for two consecutive frames, identify edge
  differences, mark the differences) either as a software program running on 
  the Zynq-7000 AP SoC PS or as a hardware accelerator inside the PL.

  The Motion Detect demonstrates how the user can seamlessly switch between a
  software or a hardware implementation and evaluate the cost and benefit of 
  each implementation. The design also demonstrates the value of offloading 
  computation intensive tasks onto PL, thereby freeing the CPU resources to be 
  available for user-specific applications.

  In Zynq Motion Detect SDSoC platform video processing algorithm(edge 
  detection, identify diff) and data mover blocks(dma) are generated and 
  integrated by SDSoC.

  This README captures pre-requisites, build and execution steps for
  motion detect command line application.


  VIDEO COMMAND APPLICATION:
  ---------------------------
  The Base TRD is an embedded video processing application designed to showcase
  various features and capabilities of Zynq Z-7020 All Programmable SoC (AP 
  SoC) device for the embedded domain. The Base TRD consists of two elements: 
  The Zynq-7000 AP SoC Processing System (PS) and a video processing pipeline
  implemented in Programmable Logic (PL). The AP SoC allows the user to 
  implement a video processing algorithm that performs edge detection on an 
  image (Sobel filter) either as a software program running on the Zynq-7000 
  AP SoC PS or as a hardware accelerator inside the PL.

  The Base TRD demonstrates how the user can seamlessly switch between a 
  software or a hardware implementation and evaluate the cost and benefit of 
  each implementation. The TRD also demonstrates the value of offloading 
  computation intensive tasks onto PL, thereby freeing the CPU resources to be
  available for user-specific applications.

  In Zynq Base TRD SDSoC platform video processing algorithm(Sobel) and data 
  mover blocks(dma) are generated and integrated by SDSoC.

  This README captures pre-requisites, build and execution steps for
  video command line application.


==============================================
3. SOFTWARE TOOLS AND SYSTEM REQUIREMENTS
==============================================

Software:
  -- SDSoC 2015.4
  -- Proper installation of required license files for the sample
     applications (Video_cmd and Motion_detect).
  -- ZC702 board uses CP210x USB to UART Bridge to provide COM port
     connection to the board. This configuration is highly recommended because
     the UART outputs information to hyper terminal right after power up.
     To use this feature, hyper terminal, Minicom, teraterm or equivalent
     terminal software on the host machine is required. For details, please
     refer to UG925 for USB-to-UART Bridge driver installation.
  -- For additional information on software installation, refer to UG798.

Hardware:
  -- The reference design targets the Zynq ZC702 evaluation board, Rev C or
     above.
  -- ZC702 evaluation board setup in the default configuration (except Boot
     switch, SW16) as documented in the Default Switch and Jumper 
     Setting of UG850.
  -- AC power adapter (12VDC)
  -- HDMI-to-HDMI or HDMI-to-DVI cable (depending on available Monitor)
  -- Monitor capable of supporting 1080p60
  -- USB Type A Male to USB Mini-B Male cable to use USB-to-UART
     bridge
  -- Optional: Avnet FMC IMAGEON daughter card (any of the below) for video
     input with 1080p input video source
        . Model: BD-FMC-IMAGEON-G  Version: FMC-IMAGEON-PCB-A
        . Model: BD-FMC-IMAGEON-G  Version: FMC-IMAGEON-PCB-B
        . Model: BD-FMC-HDMI-CAM-G Version: FMC-HDMI-CAM-PCB-A
        . Model: BD-FMC-HDMI-CAM-G Version: FMC-HDMI-CAM-PCB-B

  -- SD memory card reader for transferring files onto the SD card.
     (not included in the package)


  NOTE: Video Test Pattern Generator IP in Vivado Project needs license. 
        If it does not exists, it can be obtained from
        http://www.xilinx.com/products/intellectual-property/tpg.html

=========================
4. DESIGN FILE HIERARCHY
=========================

The directory structure underneath this top-level folder is described below:

  zc702_trd
   |
   |-- README.txt               This file
   |
   |-- IMPORTANT_NOTICE_CONCERNING_THIRD_PARTY_CONTENT.txt
   |                            List of third party content
   |
   |-- THIRD_PARTY_NOTICES.zip  Third party notices extracted from original
   |                            sources
   |
   |-- arm-xilinx-linux-gnueabi 
   |                            This folder contains third party libraries and
   |                            headers i.e V4L2/DRM
   |
   |-- boot                     This folder contains Linux Boot Files and 
   |                            petalinux project.
   |
   |-- hardware                 This folder contains prebuilt hardware files.
   |
   |-- samples                  This folder contains templates for video 
   |                            command line and motion detect applications
   |                            (sources+headers).
   |
   |-- vivado                   This folder contains vivado project. SDSoC 
   |                            uses the platform Vivado project as a 
   |                            starting point to build an application-
   |                            tailored SoC.
   |
   |-- zc702_trd_hw.pfm         Platform Hardware Description File.
   |
   |-- zc702_trd_sw.pfm         Platform Software Description File.


==============================================
5. INSTALLATION AND OPERATING INSTRUCTIONS
==============================================

This README assumes the user has downloaded the Zynq platform for SDSoC
example applications. Extract its contents to the Motion Detect home 
directory referred to as $ZYNQ_HOME.

a) Open SDSoC IDE.

b) Select the workspace.
   Create a workspace directory and use it as SDSoC workspace.
   It is assumed that workspace is $ZYNQ_HOME/workspace.

c) Create an SDSoC project using Zynq Base TRD platform.
   File -> New -> SDSoC Project

   The templates list two applications:
      - Video Command Line application
      - Motion Detect application

   VIDEO COMMAND APPLICATION:
   --------------------------
   Put "video_cmd" as Project name
   In the Target Platform section - click on Other (browse to $ZYNQ_HOME 
   directory) and select it.
   Click on Next>
   Select "Video Command Line" template and click on Finish.

   MOTION DETECT APPLICATION:
   --------------------------
   Put "motion_detect" as Project name
   In the Target Platform section - click on Other (browse to $ZYNQ_HOME 
   directory) and select it.
   Click on Next>
   Select "Motion Detect" template and click on Finish.

d) Define SDSoC project options.
   Optimize Compile
   For optimized SW implementation it is recommended to set project
   build configuration to SDRelease.
   In Project explorer window -> Right click on the SDSoC project
   (motion_detect / video_cmd).
   Build Configurations -> Set Active -> SDRelease

e) How to configure the acceleration mode to Yes/No.

   MOTION DETECT APPLICATION:
   -------------------------
   In first iteration:
      - Run the motion detect in SW.
        This is the default mode. Motion detect algorithm is configured to 
        run in SW.
        No change needed.
      - then goto step f)  below 

   In second iteration:
      - Run the motion detect in HW.
        Offload motion detect algorithm processing to HW.
        The motion detect algorithm is spread across 5 functions, in 5 files.
        1. Function:  sobel_filter()
           File    :  $ZYNQ_HOME/samples/motion_detect/motion_filter/
                      sobel_filter.cpp

        2. Function:  sobel_filter_pass()
           File    :  $ZYNQ_HOME/samples/motion_detect/motion_filter/
                      sobel_filter_pass.cpp

        3. Function:  diff_image()
           File    :  $ZYNQ_HOME/samples/motion_detect/motion_filter/
                      diff_image.c

        4. Function:  median_char_filter_pass()
           File    :  $ZYNQ_HOME/samples/motion_detect/motion_filter/
                      median_char_filter_pass.cpp

        5. Function:  combo_image()
           File    :  $ZYNQ_HOME/samples/motion_detect/motion_filter/
                      combo_image.c
 
      In Project explorer window - Browse to src/motion_filter folder.
      Expand content of each file listed above by clicking arrow mark on 
      left side (|>)
      - Project Explorer -> |>motion_detect -> |>src -> |>motion_filter -> 
        |>sobel_filter.cpp
        On sobel_filter function-  Right Click and Toggle HW/SW[H]

      - Project Explorer -> |>motion_detect -> |>src -> |>motion_filter -> 
        |>sobel_filter_pass.cpp
        On sobel_filter_pass function-  Right Click and Toggle HW/SW[H]

      - Project Explorer -> |>motion_detect -> |>src -> |>motion_filter -> 
        |>diff_image.c
        On diff_image function-  Right Click and Toggle HW/SW[H]

      - Project Explorer -> |>motion_detect -> |>src -> |>motion_filter -> 
        |>median_char_filter_pass.cpp
        On median_char_filter_pass function-  Right Click and Toggle HW/SW[H]

      - Project Explorer -> |>motion_detect -> |>src -> |>motion_filter -> 
        |>combo_image.c
        On combo_image function-  Right Click and Toggle HW/SW[H]

        This steps completes motion detect algorithm for HW acceleration.

      - then goto step f)  below 

   VIDEO COMMAND APPLICATION:
   -------------------------
   In first iteration:
      - Run the sobel in SW.
        This is the default mode. Sobel algorithm is configured to 
        run in SW.
        No change needed.
      - then goto step f)  below 

   In second iteration:
      - Run the sobel in HW.
        Offload sobel algorithm processing to HW.
        The Sobel algorithm is in 1 function, in 1 file.
        1. Function:  sds_sobel()
           File    :  $ZYNQ_HOME/samples/video_cmd/src/sds_sobel.cpp

      In Project explorer window - Browse to src/sds_sobel.cpp file.
      Expand content of the file listed above by clicking arrow mark on 
      left side (|>)
      - Project Explorer -> |>video_cmd -> |>src -> |>src -> |>sds_sobel.cpp
        On sds_sobel function-  Right Click and Toggle HW/SW[H]

        This steps completes sobel algorithm for HW acceleration.

      - then goto step f)  below 

f) Build the project

=======================
6. Test Setup
=======================
  For test setup details, please refer to section 2 (Run the TRD Demo) in the 
  below link:
  http://www.wiki.xilinx.com/Zynq+Base+TRD+2015.4

  The test setup looks as below:
  
                                       AVNET CARD (HDMI IN)
                       +------+        +------+
                  +----| FMC1 |--------| FMC2 |----+
                  |    +------+        +------+    |
                  |                                |
              +------+       +---+                 |
              |  SD  |      5| |#| Boot Switch     |
              +------+       +---+ SW16            |		
                  |         4|#| |                 |
                  |          +---+                 |
                 +--+       3|#| |                 |
           POWER |  |        +---+                 |
                 +--+       2| |#|       ZC702     |
                  |          +---+       BOARD     |
                  |         1| |#|                 |
              P1 +--+        +---+                 |
      TO MONITOR |  |                              |
      (HDMI OUT) +--+                              |
                  |                 J1     J17     |
                  +-----------------| |----| |-----+
                                    KBD/    UART to
                                    MOUSE   LAPTOP
=======================
7. Run the application
=======================
   Copy the boot files and executable into SD card from the
     - MOTION DETECT APPLICATION:
       $ZYNQ_HOME/workspace/motion_detect/SDRelease/sd_card directory.

     - VIDEO COMMANAD APPLICATION:
       $ZYNQ_HOME/workspace/video_cmd/SDRelease/sd_card directory.

   Set the Boot switch (SW16) on the board to boot in SD mode.
   Petalinux login details:

   zynq login: root
   Password  : root

   At the command prompt on the putty/teraterm:
     - MOTION DETECT APPLICATION:
       /media/card/motion_detect.elf

     - VIDEO COMMAND APPLICATION:
       /media/card/video_cmd.elf

   Output screen looks as below:
     - MOTION DETECT APPLICATION:

       --------------- Select Video Source ---------------
         1 : Test Pattern Generator(*)
         2 : HDMI Input
       ---------------Select Filter Type ----------------
         3 : Motion Detect  (*)
       --------------- Toggle Filter Mode ----------------
         4 : Filter OFF/ON  (OFF)
       --------------- Exit Application ------------------
         0 : Exit

     - VIDEO COMMAND APPLICATION:
       --------------- Select Video Source ---------------
         1 : Test Pattern Generator(*)
         2 : HDMI Input
       ---------------Select Filter Type ----------------
         3 : Sobel  (*)
       --------------- Toggle Filter Mode ----------------
         4 : Filter OFF/ON  (OFF)
       --------------- Exit Application ------------------
         0 : Exit


  Toggle Filter ON (4) to enable the Motion Detect / Sobel filter.
  In first iteration of scenario (e), the filter is run in software and 
  the achieved frame rate is < 4fps.
  In second iteration of scenario (e), the filter is run accelerated in 
  the PL and the achieved frame rate is 60fps.

1) Design Notes
    (a) The edge detection algorithm, that is part of Motion Detect is 
        influenced by the color contrast in frame content. Hence, maximum 
        motion is detected for High contrast colors, whereas motion may not 
        be detected for all edges that are having low contrast in colors.
        Please try the video from below link, that has high contrast in 
        frames, hence maximum motion is detected.
        https://www.youtube.com/watch?v=sYSvdXTCd50

    (b) This design is ported from 2015.2. It is currently supporting 1080p
        resolution (1920x1080 @ 60Hz) only.

2) Known Issues

	(1) Vivado - "ERROR: [Common 17-143] Path length exceeds 260-Byte
            maximum allowed by Windows"
            Please refer AR# 52787 for more details.
            Link: http://www.xilinx.com/support/answers/52787.html

=======================
9. SUPPORT
=======================

To obtain technical support for this reference design, go to 
www.xilinx.com/support
to locate answers to known issues in the Xilinx Answers Database.


=======================
END OF DOCUMENT
=======================

