.gitignore

@@ -64,13 +64,4 @@
 .AppleDesktop
 Network Trash Folder
 Temporary Items
-.apdisk
+.apdisk
-
-
-__pycache__/
-*.py[cod]
-venv/
-.idea/
-
-old/
-

README.md

@@ -1,10 +1,18 @@
 # 下位机
 
-下位机按上位机指令根据传送带脉冲等触发相机，完成棉花异性纤维的分选任务。采用的硬件是[Alinx](https://www.alinx.com/)的AC7Z100C ZYNQ开发板。
+下位机按上位机指令根据传送带脉冲等触发相机，完成刨花板的缺陷分选任务。本次下位机不连接阀板，是由PLC翻板机的机械装置作为执行器，对木板进行分选。采用的硬件是[Microphase](https://www.microphase.cn/)的XME0724CB ZYNQ开发板，具体核心板型号为XME0724-10，到手后记得把各排插针焊一下，如左图：
 
-本IO扩展版提供了
+![1](README.assets/1.jpg)
 
-- xxxxxx
+为了供电稳定，采用叠板给底板5V供电，由底板输出3.3V供回给叠板，叠板就是IO扩展板，将IO扩展板插在底板排针上，叠起来，因此称为叠板，如上图中和上图右。
+
+IO扩展版提供了
+
+- 1个12V电源输入
+- 4个相机触发，本次项目为2个相机触发，其余冗余
+- 1个ZYNQ散热风扇接口 
+- 6个编码器或IO输入，本次项目为1个编码器输入、1个物体传感器输入，其余冗余
+- 8个阀板接口，本次项目没有用到
 
 接线时，12V电源连接到IO扩展板的电源接口，相机线应连接相机触发接口`TRIG1`、`TRIG2`和对应的`GND`接口，编码器线应连接在编码器输入接口`E1`和对应的`GND`接口，物体传感器应连接输入接口`E3`和对应的`GND`接口。注意底板不连接任何外部电源。
 
@@ -17,7 +25,6 @@
   - [develop_and_deploy.md](doc/develop_and_deploy.md)为开发和部署说明，首先看这个文档
   - [hardware_description.md](doc/hardware_description.md)为PL端逻辑设计说明，阐述了硬件工作的整体流程
   - [pl_reference_mannual.md](doc/pl_reference_mannual.md)为PL端逻辑在AXI总线上映射的寄存器参考手册
-  - [sim_uppermachine_manual.md](doc/sim_uppermachine_manual.md)为模拟上位机运行的参考手册
 
 - script为配置系统、安装环境、安装可执行文件、卸载可执行文件等的脚本
 
@@ -35,14 +42,13 @@
   - pl_platform为PL端硬件设计
   - xme0724ioextend为IO叠板的原理图和PCB
 
-- source为AC7Z100C板子上运行的源程序和模拟上位机程序
+- source为XME0724板子上运行的源程序
 
   - liunx_app为Linux上运行的应用程序，即业务逻辑
   - linux_driver为Linux上的驱动，用于控制自定义的PL端硬件，其中drv_test结尾的目录为相应驱动模块的测试应用程序
   - petalinux_config为petalinux工具在编译u-boot、kernel、rootfs前进行的配置
   - petalinux_devicetree为本次自定义的Linux设备树文件部分，其余设备树为自动生成的
   - petalinux_hwdescription为petalinux所使用的硬件描述文件，包含了vivado工程中的比特流等信息
-  - sim_uppermachine_manul为基于pyside6所编写的软件，用于模拟上位机发送指令，方便调试
 
 ## 版本
 
@@ -68,4 +74,4 @@ b分支编号-d文档版本-hPCB设计版本-lFPGA设计版本-p协议版本-s
 
 ##  作者
 
-作者徐耀，随时欢迎师弟师妹7x24提着示波器的来问问题，联系方式：QQ：1170701029；微信：CeRnYool。
+作者觉得还是不说明作者是谁比较好，免得毕业后有提着示波器的师弟师妹来问问题

doc/develop_and_deploy.md

@@ -0,0 +1,365 @@
+# 开发和部署
+
+## 开发
+
+本次开发基于zynq `xc7z010-1clg400`芯片，因此FPGA设计软件为Vitis中包含的[Vivado 2022.1](https://china.xilinx.com/support/download/index.html/content/xilinx/zh/downloadNav/vitis.html)，Linux编译工具为[petalinux 2022.2](https://china.xilinx.com/support/download/index.html/content/xilinx/zh/downloadNav/embedded-design-tools.html)，Linux应用程序编译工具为linaro的[arm-linux-gnueabihf-gcc 12.2.1](https://snapshots.linaro.org/gnu-toolchain/12.2-2023.04-1/)。
+
+### 生成硬件描述文件
+
+1. 下载[hardware/pl_platform](../hardware/pl_platform)文件夹到家目录，这里假设用户为miaow<br />在vivado 2022.1中执行tcl脚本，复原工程
+    ```tcl
+    source /home/miaow/pl_platform/lower_machine.tcl
+    ```
+
+2. 重新生成`block design`的`output products`
+
+3. 生成`bitstream`后创建硬件描述文件，命令为
+    ```tcl
+    # 下面命令中32为计算机逻辑内核数，按实际设定
+    launch_runs impl_1 -to_step write_bitstream -jobs 32
+
+    # 生成硬件描述文件
+    write_hw_platform -fixed -include_bit -force -file /home/miaow/zynq/vivado_git/lower_machine/system_wrapper.xsa
+    ```
+   硬件描述文件为`system_wrapper.xsa`
+
+### 创建PETALINUX工程
+
+1. 创建名为`ps-linux`的工程
+
+   ```shell
+   $ cd ~
+   $ petalinux-create -t project --template zynq -n ps-linux
+   ```
+   
+2. 上传release中的硬件描述文件`system_wrapper.xsa`到`ps-linux`目录中并config
+
+   ```shell
+   system_wrapper.xsa上传到~/ps-linux
+   $ petalinux-config --get-hw-description system_wrapper.xsa
+   ```
+
+   在`petalinux-config`时候，按下面提示配置
+
+   ```shell
+   # Subsystem AUTO Hardware Settings
+   # ├─Serial Settings
+   # | ├─FSBL Serial stdin/stdout (设为ps7_uart_0)
+   # | ├─DTG Serial stdin/stdout (设为ps7_uart_0)
+   # | └─System stdin/stdout baudrate for ps7_uart_0 (设为115200)
+   # ├─Ethernet Settings
+   # | ├─Randomise MAC address (不选)
+   # | ├─Primary Ethernet (设为ps7_ethernet_0)
+   # | ├─Obtain IP address automatically (不选)
+   # | ├─Static IP address (设为192.168.10.10)
+   # | ├─Static IP netmask (设为255.255.255.0)
+   # | └─Static IP gateway (设为192.168.10.1)
+   # ├─Flash Settings
+   # | └─Primary Flash (设为ps7_qspi_0)
+   # ├─Flash Settings
+   # | └─Primary Flash (设为ps7_qspi_0)
+   # ├─SD/SDIO Settings
+   # | └─Primary SD/SDIO (设为ps7_sd_0)
+   # Image Packaging Configuration
+   # └─Image Packaging Configuration
+   #   ├─Root filesystem type (设为EXT4 (SD/eMMC/SATA/USB))
+   #   ├─name for bootable kernel image (设为image.ub)
+   #   ├─Root filesystem formats (设为tar.gz)
+   #   └─Copy final images to tftpboot (不选)
+   ```
+
+4. 创建一个模块
+
+    ```shell
+    $ petalinux-create -t modules --name encoder --enable
+    ```
+
+1. 上传驱动代码[source/linux_driver/encoder.c](../source/linux_driver/encoder.c)到下面的目录中
+
+   ```shell
+   ~/ps-linux/project-spec/meta-user/recipes-modules/encoder/files
+   ```
+
+1. 修改设备树，需要修改的文件为`project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`，先删除该文件，然后上传新的自定义设备树文件[source/petalinux_devicetree/system-user.dtsi](../source/petalinux_devicetree/system-user.dtsi)
+
+   ```shell
+   $ cd ~/ps-linux/project-spec/meta-user/recipes-bsp/device-tree/files
+   $ rm system-user.dtsi
+   上传source/petalinux_devicetree/system-user.dtsi
+   ```
+
+2. 配置`kernel`，使用命令`petalinux-config -c kernel`，按下面提示或[source/petalinux_config/kernel.cfg](../source/petalinux_config/kernel.cfg)配置
+
+   ```shell
+   # File systems
+   # ├─FUSE (Filesystem in Userspace) support (勾选为星号)
+   # └─DOS/FAT/EXFAT/NT Filesystems
+   #   ├─Enable FAT UTF-8 option by default (勾选为星号)
+   #   ├─exFAT filesystem support (勾选为星号)
+   #   ├─NTFS file system support (勾选为星号)
+   #   └─NTFS write support (勾选为星号)
+   # Device Drivers
+   # └─USB support
+   #   └─OTG support (勾选为星号)
+   ```
+
+3. 配置`rootfs`，使用命令`petalinux-config -c rootfs`，按下面提示或[source/petalinux_config/rootfs_config](../source/petalinux_config/rootfs_config)配置
+
+   ```shell
+   # Filesystem Packages
+   # ├─base
+   # | ├─shell
+   # | | └─bash
+   # | |   └─bash (勾选为星号)
+   # | ├─tar
+   # | | └─tar (勾选为星号)
+   # | ├─util-linux
+   # | | ├─util-linux-blkid (勾选为星号)
+   # | | ├─util-linux-lscpu (勾选为星号)
+   # | | ├─util-linux-umount (勾选为星号)
+   # | | └─util-linux-mount (勾选为星号)
+   # | └─xz
+   # |   ├─xz (勾选为星号)
+   # |   └─liblzma (勾选为星号)
+   # ├─console
+   # | ├─network
+   # | | ├─curl
+   # | | | ├─curl (勾选为星号)
+   # | | | └─libcurl (勾选为星号)
+   # | | ├─dropbear
+   # | | | └─dropbear (不选)
+   # | | ├─ethtool
+   # | | | └─ethtool (勾选为星号)
+   # | | ├─lrzsz
+   # | | | └─lrzsz (勾选为星号)
+   # | | ├─minicom
+   # | | | └─minicom (勾选为星号)
+   # | | ├─openssh
+   # | | | ├─openssh (勾选为星号)
+   # | | | ├─openssh-misc (勾选为星号)
+   # | | | ├─openssh-sshd (勾选为星号)
+   # | | | ├─openssh-keygen (勾选为星号)
+   # | | | ├─openssh-ssh (勾选为星号)
+   # | | | ├─openssh-sftp (勾选为星号)
+   # | | | ├─openssh-sftp-server (勾选为星号)
+   # | | | └─openssh-scp (勾选为星号)
+   # | | └─wget
+   # | |   └─wget (勾选为星号)
+   # | ├─utils
+   # | | ├─bash-completion
+   # | | | ├─bash-completion (勾选为星号)
+   # | | | └─bash-completion-extra (勾选为星号)
+   # | ├─bzip2
+   # | | ├─bzip2 (勾选为星号)
+   # | | └─libbz2 (勾选为星号)
+   # | ├─file
+   # | | └─file (勾选为星号)
+   # | ├─findutils
+   # | | └─findutils (勾选为星号)
+   # | ├─gawk
+   # | | └─gawk (勾选为星号)
+   # | ├─grep
+   # | | └─grep (勾选为星号)
+   # | ├─gzip
+   # | | └─gzip (勾选为星号)
+   # | ├─less
+   # | | └─less (勾选为星号)
+   # | ├─man
+   # | | └─man (勾选为星号)
+   # | ├─man-pages
+   # | | └─man-pages (勾选为星号)
+   # | ├─screen
+   # | | └─screen (勾选为星号)
+   # | ├─sed
+   # | | └─sed (勾选为星号)
+   # | ├─unzip
+   # | | └─unzip (勾选为星号)
+   # | ├─vim
+   # | | ├─vim (勾选为星号)
+   # | | ├─vim-syntax (勾选为星号)
+   # | | └─vim-common (勾选为星号)
+   # | └─zip
+   # |   └─zip (勾选为星号)
+   # ├─devel
+   # | └─lsof
+   # |   └─lsof (勾选为星号)
+   # ├─libs
+   # | ├─ncurses
+   # | |  ├─ncurses (勾选为星号)
+   # | |  ├─ncurses-terminfo-base (勾选为星号)
+   # | |  ├─ncurses-tools (勾选为星号)
+   # | |  └─ncurses-terminfo (勾选为星号)
+   # | └─which
+   # |    └─which (勾选为星号)
+   # ├─misc
+   # | ├─perf
+   # | | └─perf (勾选为星号)
+   # | └─packagegroup-core-ssh-dropbear
+   # |   └─packagegroup-core-ssh-dropbear (不选)
+   # Image Features
+   # ├─imagefeature-ssh-server-dropbear (不选)
+   # ├─imagefeature-ssh-server-openssh (勾选为星号)
+   # ├─imagefeature-hwcodecs (勾选为星号)
+   # ├─imagefeature-package-management (勾选为星号)
+   # modules
+   # ├─encoder (不选)
+   # PetaLinux RootFS Settings
+   # ├─ADD_EXTRA_USERS (root:3703;petalinux:3703;)
+   # ├─ADD_USERS_TO_GROUPS (petalinux:audio,video;)
+   # └─ADD_USERS_TO_SUDOERS (petalinux)
+   ```
+
+8. 替换`~/ps-linux/project-spec/meta-user/recipes-bsp/u-boot/files/platform-top.h`为[platform-top.h](../source/petalinux_config/platform-top.h)，用于添加u-boot所需的环境变量，实现动态加载比特流文件
+
+### 编译系统
+
+1. 编译工程，使用命令`petalinux-build`。编译完成，在当前工程目录下生成`images`文件夹，该命令将生成设备树文件、`FSBL`文件、`U-Boot`文件，`Linux Kernel`文件和`rootfs`文件镜像
+
+2. 制作BOOT.BIN启动文件，具体命令如下：
+
+   ```shell
+   $ cd ~/ps-linux/images/linux/  # 生成的BOOT.BIN在该路径下
+   $ petalinux-package --boot --fsbl ./zynq_fsbl.elf --u-boot ./u-boot.elf --force
+   ```
+   
+
+### 编译驱动
+
+依次运行如下命令，编译驱动程序
+
+```shell
+$ petalinux-build -c encoder
+```
+
+编译后的模块文件为`ps-linux/build/tmp/sysroots-components/zynq_generic/encoder/lib/modules/5.15.36-xilinx-v2022.2/extra/encoder.ko`
+
+### 编译应用程序
+
+在运行make时要设置好交叉编译工具链前缀，命令如下
+```shell
+$ make CROSS_COMPILE=交叉编译工具链前缀
+例如 make CROSS_COMPILE=/home/miaow/software/gcc-linaro-12.2.1-2023.04-x86_64_arm-linux-gnueabihf/bin/arm-none-linux-gnueabihf-
+```
+
+编译后的可执行文件为工程目录的`build/target`，交叉编译工具链前缀也可以在Makefile中修改设定
+
+## 部署
+
+有两种方式部署，一种是修改文件系统，这也是我第一次构建这个系统时的操作；另一种是直接写入镜像，推荐使用这种方式，省时省力不易出错
+
+> 注意：修改文件系统方法所需的文件按上一章节编译得到或者从github的release中下载；直接写入镜像所需的文件在release中
+
+
+### 修改文件系统
+
+1. 给SD卡创建DOS分区表，然后分2个区并创建文件系统，细节如下表：
+
+   | 扇区           | 大小           | 分区类型          | 文件系统 | 卷标   |
+   | -------------- | -------------- | ----------------- | -------- | ------ |
+   | 2048~x扇区     | 100M           | C W95 FAT32 (LBA) | FAT32    | boot   |
+   | x扇区~最后扇区 | ≈SD卡大小-100M | 83 Linux          | ext4     | rootfs |
+
+2. 将打包和编译得到的`BOOT.BIN`、`boot.scr`、`system.bit`和`image.ub`复制到`boot`分区；将`rootfs.tar.gz`解压到`rootfs`分区
+
+   这里的`system.bit`为比特流文件，可以由`petalinux`从`XSA`文件中提取，也可以是`vivado`生成的，注意重命名为`system.bit`。
+
+3. 拨码开关拨到SD卡启动，插入SD卡到XME0724底板上，上电启动。
+
+4. 终端软件连接底板上的串口，波特率115200，8位，1停止位，无校验
+
+> 注意：github的release中包含了修改完成的`rootfs.tar.gz`，因此无需重复下面的步骤，这里仅用作记录修改步骤
+
+5. 修改`/etc/shadow`文件，将`root`用户的密码删除，切换到`root`用户并设定密码为`3703`，具体命令如下:
+
+   ```shell
+   $ sudo sed "1c root::15069:0:99999:7:::" /etc/shadow
+   # 如果没有sed命令，用任何其他方式都可以，比如vim
+   $ su root
+   $ passwd
+   ```
+
+
+6. 配置网络和`ssh`服务，用`root`登录：
+
+   ```shell
+   $ vi /etc/network/interfaces
+     添加或确认内容如下：
+     auto eth0
+     iface eth0 inet static
+       address 192.168.10.10
+       netmask 255.255.255.0
+       gateway 192.168.10.1
+   $ vi /etc/ssh/sshd_config
+     确认修改如下选项：
+     PermitRootLogin yes
+     PermitEmptyPasswords yes
+     PasswordAuthentication yes
+   $ reboot
+   ```
+
+7. 电脑网卡设置到开发板同一网段 SSH连接信息如下
+
+   ```shell
+   在电脑上执行下面命令
+   $ sshpass -p "3703" ssh root@192.168.10.10 -p 22
+   ```
+
+8. 安装编译得到的驱动文件`encode.ko`，并设置自动加载，对应自启脚本可以如下方式写入，也可以直接上传[script/loadencoder.sh](../script/loadencoder.sh)，ssh方式，`root`登录:
+
+   ```shell
+   上传encoder.ko到/lib/modules/[内核版本]/extra/
+   $ cd /lib/modules/[内核版本]/extra/; depmod
+   $ set +H
+   $ echo -e "#!/bin/sh\nmodprobe encoder" > /etc/init.d/loadencoder.sh
+   $ chmod 755 /etc/init.d/loadencoder.sh
+   $ cd /etc/rc5.d 
+   $ ln -s ../init.d/loadencoder.sh S20loadencoder.sh
+   ```
+   
+9. 安装编译得到的应用程序target，并设置自启动，对应脚本见[script/target.sh](../script/target.sh)
+
+   ssh方式，root登录:
+
+   ```shell
+   上传target到/home/root
+   $ cd ~
+   $ chmod 755 target
+   $ set +H
+   $ echo -e "#!/bin/sh\nif [ -x /home/root/target ]; then\n /home/root/target\nfi" > /etc/init.d/target.sh
+   $ chmod 755 /etc/init.d/target.sh
+   $ cd /etc/rc5.d
+   $ ln -s ../init.d/target.sh S99target.sh
+   ```
+
+10. \[可选\] 设置`.bashrc`，修改`PS1`，对应脚本见[script/.profile](../script/.profile)和[script/.bashrc](../script/.bashrc)
+
+    ```shell
+    $ cd ~; rm .bashrc .profile
+    上传.bashrc和.profile到/home/root
+    $ if [ ! -a /home/petalinux/.profile ]; then cp /home/    root/.profile /home/petalinux/ fi
+    $ if [ ! -a /home/petalinux/.bashrc ]; then cp /home/root/.    bashrc /home/petalinux/ & chown petalinux:petalinux -R /    home/petalinux fi
+    $ source ~/.profile
+    ```
+
+11. \[可选\] 安装`ncurses-6.3`和`htop`
+
+    ```shell
+    $ cd ~; rz  # 上传ncurses-6.3.tar.gz
+    $ tar xmzf /home/root/ncurses-6.3.tar.gz -C /usr/
+    $ rz  # 上传htop.tar.gz
+    $ tar xmzf /home/root/htop.tar.gz -C /usr/
+    $ echo "export TERMINFO=/usr/share/terminfo" >> /etc/profile
+    $ reboot
+    ```
+
+### 直接写入镜像
+
+强烈推荐的傻瓜式的方法，在windows上准备好正版[DiskGenius标准版或专业版](https://www.diskgenius.cn/)，盗版有概率写入错误数据，从release中下载`sdimage.pmfx`文件
+
+1. 在windows上插入16G的TF卡
+2. 打开`DiskGenius`
+3. 左侧栏选中TF卡，右键，从镜像文件还原磁盘
+4. 选`sdimage.pmfx`文件
+5. 点击开始
+
+把TF卡插回板子，启动方式拨到SD卡启动，上电。要进入系统，参考修改文件系统章节的第7步。

doc/hardware_description.md

@@ -0,0 +1,46 @@
+# 硬件平台
+
+PL端主要由2个外设组成，分别时**风扇控制器**(FAN)，**编码和分频控制器**(ENCODER)，各个控制器的连接关系如下图所示。
+
+![2](hardware_description.assets/system_arch.svg)
+
+由于开发板的PL端没有自带晶振，所以2个外设由统一的同步时钟驱动，时钟源来自PS端，为200MHz，软件不可修改。外部编码器信号和物体检测传感器信号输入**编码和分频控制器**，控制器根据软件设置的阀触发分频值和相机触发分频值对编码器信号进行分频，分频后的信号用于触发相机拍照。
+
+**风扇控制器**用于驱动风扇的启停，给ZYNQ芯片进行降温，防止芯片过热导致工作中出现问题。由于风扇寿命短，因此目前采用散热片方案，风扇不开。
+
+## PS模块
+
+下面列出需要开启的外设和采用的IO口，BANK0为LVCMOS3.3V，BANK1为LVCOMS1.8V
+
+| 外设                                                | IO                     | 备注                                   |
+| --------------------------------------------------- | ---------------------- | -------------------------------------- |
+| Quad SPI Flash                                      | 1~6                    | Single SS 4bit IO，Fast , ss_b pullup  |
+| Ethernet 0<br />MDIO                                | 16~27<br /> 52~53      | Fast, all pullup                       |
+| USB0                                                | 28~39                  | Fast, all pullup                       |
+| SD0                                                 | 40~45                  | Fast, all pullup                       |
+| SD1                                                 | 46~51                  | Fast, all pullup                       |
+| UART0                                               | 14~15                  | all pullup, baud 115200, 8bits, 1 stop |
+| TTC0                                                | EMIO                   |                                        |
+| GPIO MIO<br />Ethernet PHY Reset<br />USB PHY Reset | 所有剩下的<br/>7<br/>8 | Fast, all pullup                       |
+
+时钟配置上，ARM为666.66MHz，DDR为533.33MHz，用IOPLL给PL端提供200MHz的FCLK_CLK0。
+
+如果用的是7010的板子，内存选忽略下面这一段：内存配置上，选择DDR3，数据位宽32bit=16bit/chip \* 2chip, 4096Mbits/chip，频率533.33，速度等级为1066F，行/列/Bank地址宽度为15/10/3，CL=7，CWL=6，RCD=7，RP=7，RC=51ns，FAW=40ns
+
+ARM核上还开启AXI GP0接口与PL通信
+
+## ENCODER模块
+
+encoder模块主要接口为in_signal、out_signal_camera_a_posedge、out_signal_camera_b_posedge、out_signal_camera_c_posedge、out_signal_camera_d_posedge、out_signal_valve_posedge、out_signal_camera_a、out_signal_camera_b、out_signal_camera_c、out_signal_camera_d、out_signal_valve、exrst_n
+
+终于，我们重新实现了被老倪乱起八糟的需求搞的几乎奔溃的模块，现在这个模块已经比较简洁了
+
+1. in_signal接口与外部编码器相连，接收外部编码器信号
+2. out_signal_camera_a到d最多课用于触发共4个相机
+3. out_signal_camera_posedge_a到d为上述信号的上升沿，固定不连接。
+4. out_signal_valve_posedge为out_signal_valve的上升沿，固定不连接。
+5. exrst_n为可选的外部复位清零信号，可用于连接物体传感器，根据需要屏蔽相机触发输出
+
+
+ENCODER模块输入输出频率的详细计算方式和寄存器说明见[doc/pl_reference_mannual.md](pl_reference_mannual.md)中的ENCODER控制器部分
+

doc/pl_reference_mannual.assets/fan_block.svg

@@ -0,0 +1 @@
+<svg width="1226" height="662" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" overflow="hidden"><defs><clipPath id="clip0"><rect x="1440" y="922" width="1226" height="662"/></clipPath></defs><g clip-path="url(#clip0)" transform="translate(-1440 -922)"><path d="M1440 1415 1594.99 1415" stroke="#B4C7E7" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1467 1140 1621.66 1140" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2504 1228 2658.66 1228" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1551.5 984.391C1551.5 951.866 1577.87 925.5 1610.39 925.5L2503.61 925.5C2536.13 925.5 2562.5 951.866 2562.5 984.391L2562.5 1521.61C2562.5 1554.13 2536.13 1580.5 2503.61 1580.5L1610.39 1580.5C1577.87 1580.5 1551.5 1554.13 1551.5 1521.61Z" stroke="#2F5597" stroke-width="6.875" stroke-miterlimit="8" fill="#DAE3F3" fill-rule="evenodd"/><text font-family="Arial,Arial_MSFontService,sans-serif" font-weight="700" font-size="73" transform="matrix(1 0 0 1 2378.67 1268)">SPD<tspan font-size="73" x="-800.976" y="-85">EN</tspan><tspan fill="#767171" font-size="73" x="-800.976" y="162">FAN</tspan></text></g></svg>

doc/pl_reference_mannual.assets/fifo_block.svg

@@ -0,0 +1 @@
+<svg width="1398" height="862" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" overflow="hidden"><defs><clipPath id="clip0"><rect x="1180" y="712" width="1398" height="862"/></clipPath></defs><g clip-path="url(#clip0)" transform="translate(-1180 -712)"><path d="M1180 1330 1356.99 1330" stroke="#2F5597" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1180 1214 1356.99 1214" stroke="#2F5597" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1180 1087 1356.99 1087" stroke="#2F5597" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385.5 855.5 2562.49 855.5" stroke="#B4C7E7" stroke-width="20.625" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385 973 2561.99 973.001" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385 1093 2561.99 1093" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385 1214 2561.99 1214" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385 1330 2561.99 1330" stroke="#2F5597" stroke-width="10.3125" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M2385.5 1447.5 2562.49 1447.5" stroke="#2F5597" stroke-width="20.625" stroke-linecap="square" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1180 844 1334.99 844" stroke="#B4C7E7" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1180 962 1356.99 962.001" stroke="#B4C7E7" stroke-width="10.3125" stroke-miterlimit="8" fill="none" fill-rule="evenodd"/><path d="M1289.5 792.373C1289.5 749.917 1323.92 715.5 1366.37 715.5L2369.63 715.5C2412.08 715.5 2446.5 749.917 2446.5 792.373L2446.5 1493.63C2446.5 1536.08 2412.08 1570.5 2369.63 1570.5L1366.37 1570.5C1323.92 1570.5 1289.5 1536.08 1289.5 1493.63Z" stroke="#2F5597" stroke-width="6.875" stroke-miterlimit="8" fill="#DAE3F3" fill-rule="evenodd"/><text fill="#767171" font-family="Arial,Arial_MSFontService,sans-serif" font-weight="700" font-size="73" transform="matrix(1 0 0 1 1874.98 867)">DT_OUT<tspan font-size="73" x="292.76" y="0">[</tspan><tspan font-size="73" x="317.396" y="0">383:0</tspan><tspan font-size="73" x="504.74" y="0">]</tspan><tspan fill="#000000" font-size="73" x="236.615" y="124">xEMPTY</tspan><tspan fill="#000000" font-size="73" x="342.604" y="247">FULL</tspan><tspan fill="#000000" font-size="73" x="-72.7605" y="370">ALMOST_EMPTY</tspan><tspan fill="#000000" font-size="73" x="-7.448" y="493">ALMOST_FULL</tspan><tspan fill="#000000" font-size="73" x="73.3333" y="616">COUNT[11:0]</tspan><tspan font-size="73" x="-518.112" y="0">FIFO_VALID</tspan><tspan font-size="73" x="-518.112" y="124">RD_SYN</tspan><tspan fill="#000000" font-size="73" x="-518.112" y="247">WR_SYN</tspan><tspan fill="#000000" font-size="73" x="-518.112" y="370">CLEAR</tspan><tspan fill="#000000" font-size="73" x="-518.112" y="493">DT_IN</tspan><tspan fill="#000000" font-size="73" x="-306.705" y="493">[383:0]</tspan></text></g></svg>

doc/pl_reference_mannual.md

@@ -0,0 +1,139 @@
+# PL 端自定义外设参考手册
+
+## 存储器和总线架构
+
+### 系统架构
+
+PL端主要由2个外设组成，分别时**风扇控制器**(FAN)，**编码和分频控制器**(ENCODER)。各个控制器的连接关系如下图所示。
+
+![system_arch](./pl_reference_mannual.assets/system_arch.svg)
+
+2个外设由统一的同步时钟驱动，时钟源来自PS端，为200MHz，软件不可修改。外部编码器信号和物体传感器信号输入**编码和分频控制器**，控制器根据软件设置的相机触发分频值对编码器信号进行分频。为同步触发相机。
+
+具体的硬件设计和信号说明见[doc/hardware_description.md](hardware_description.md)
+
+各控制器的边界地址和所属总线等信息如下表所示
+
+| 边界地址                | 外设             | 总线      |
+| ----------------------- | ---------------- | --------- |
+| 0x43c10000 - 0x43c1ffff | 编码和分频控制器 | M_AXI_GP0 |
+| 0x43c20000 - 0x43c2ffff | 风扇控制器       | M_AXI_GP0 |
+
+## 风扇控制器 (FAN)
+
+### FAN简介
+
+FAN模块用于控  制散热风扇的启停以及通过PWM调整风扇速度。通过对寄存器写入值，该模块能正常启停散热风扇，但由于代码与硬件兼容问题，导致无法观察到调速现象。
+
+### FAN主要特性
+
+- 能控制风扇的启停
+- 自定义占空比，调整风扇转速
+
+### FAN功能说明
+
+<img src="pl_reference_mannual.assets/fan_block.svg" alt="fan_block" style="zoom:20%;" />
+
+通过将开启使能拉高，开启风扇。通过向风速寄存器写入PWM占空值，控制风扇减少或提高风速。
+
+### FAN寄存器说明
+
+FAN模块寄存器主要包括控制寄存器 (FAN_CR)、风速寄存器 (FAN_SPDR)。控制寄存器 (FAN_CR)用于控制风扇开启或关闭的状态，风速寄存器 (FAN_SPDR)通过PWM技术设置风扇转动的速度。
+
+**Base Address: 0x43c20000**  
+
+#### FAN控制寄存器 (FAN_CR)
+
+偏移地址: 0x00<br/>复位值: 0x0000 0000
+
+![fan_cr](pl_reference_mannual.assets/fan_cr.png)
+
+| **Field**    | **Description**                                              |
+| :----------- | :----------------------------------------------------------- |
+| 位31:16 保留 | 必须保持复位值                                               |
+| 位0 **EN**   | 内部触发信号 (Virtual Triggle Signal)<br />    0: 停止风扇<br/>    1: 开启风扇 |
+
+#### FAN风速寄存器 (FAN_SPDR)
+
+偏移地址: 0x04<br/>复位值: 0x0000 0000
+
+![fan_spdr](pl_reference_mannual.assets/fan_spdr.png)
+
+| **Field**      | **Description**                                              |
+| :------------- | :----------------------------------------------------------- |
+| 位31:0 **SPD** | 该寄存器值表示设置的风扇PWM占空值，占空比转换公式如下。<br />占空比% = SPD / (2 ^ 32 - 1) * 100% |
+
+#### FAN寄存器映射
+
+FAN寄存器可映射为32位可寻址寄存器，如下表所述：
+
+![fan_regs](pl_reference_mannual.assets/fan_regs.png)
+
+## 编码和分频控制器 (ENCODER)
+
+### ENCODER简介
+
+ENCODER模块主要用于实现编码器计数以及对编码器脉冲进行分频，分频后的脉冲信号输出给相机。该模块包括1个控制寄存器 (ENCODER_CR)、阀触发分频寄存器 (ENCODER_VDIVR)、相机触发分频寄存器 (ENCODER_CDIVR)。
+
+### ENCODER主要特性
+
+- 独立设置对相机和喷阀的分频系数
+- 内外两种触发模式选择
+- 可选的外部清零方式
+
+### ENCODER功能说明
+
+下图给出了ENCODER的主要信号：
+
+<img src="pl_reference_mannual.assets/encoder_block.svg" alt="图片1" style="zoom: 20%;" />
+
+ENCODER模块接收编码器脉冲信号，通过设置的相机和喷阀分频系数，生成对应的触发信号。编码器脉冲信号可由内部或外部触发模式产生。
+
+### ENCODER寄存器说明
+
+ENCODER模块的寄存器主要有控制寄存器 (ENCODER_CR)、阀触发分频寄存器 (ENCODER_VDIVR)和相机触发分频寄存器 (ENCODER_CDIVR)。控制寄存器 (ENCODER_CR)用于进行触发模式选择以及复位清空，阀触发分频寄存器 (ENCODER_VDIVR)用于寄存输入的分频系数，将编码器脉冲除以分频系数得到触发脉冲。
+
+**Base Address: 0x43c10000**
+
+#### ENCODER控制寄存器 (ENCODER_CR)
+
+偏移地址: 0x00<br/>复位值: 0x0000 0008
+
+![ ](pl_reference_mannual.assets/encoder_cr.svg)
+
+| **Field**   | **Description**                                              |
+| :---------- | :----------------------------------------------------------- |
+| 位31:4 保留 | 必须保持复位值                                               |
+| 位3 **ICO** | 仅限内部清除缓存 (Internal Clear Only)<br />    0: 同时允许由外部输入**Ex CLR**和清除缓存位**CLR**控制进入清零状态<br />        清零状态见位**CLR**的描述；外部输入为高时，退出清零状态<br />    1: 仅限内部信号清除缓存 |
+| 位2 **VTS** | 内部触发信号 (Virtual Triggle Signal)<br />    **MOD**位置1时，由软件写入，将该位信号直接充当触发信号<br />    0: 低电平<br />    1: 高电平 |
+| 位1 **MOD** | 模式选择 (Mode)<br />    0: 外部触发模式，外部触发编码器转动<br />    1: 内部触发模式，软件模拟触发信号 |
+| 位0 **CLR** | 清除缓存 (Clear)<br />   0: 清除编码和分频控制器内部的分频计数值，不影响ENCODER_VDIVR和ENCODER_CDIVRx<br /> 注意: 程序清零该位后需再写入1，使计数器退出清零状态，正常工作 <br />   1: 正常工作 |
+
+#### ENCODER阀触发分频寄存器 (ENCODER_VDIVR)
+
+偏移地址: 0x04<br/>复位值: 0x0000 0000
+
+![image-20220613202916591](pl_reference_mannual.assets/encoder_vdivr.svg)
+
+| **Field**       | **Description**                                              |
+| :-------------- | :----------------------------------------------------------- |
+| 位31:0 **VDIV** | 阀触发分频值<br />    阀控制器重采样频率和编码器脉冲的分频值， 写入数据后编码和分频控制器自动清除缓存并应用新的数值 <br />    注意：0表示不间断触发，即PL端每个时钟周期均触发阀模块 |
+
+#### ENCODER相机触发分频寄存器 (ENCODER_CDIVRx)  (x=A...D) 
+
+用于设定相机A到相机D的分频系数，各相机可独立设置
+
+偏移地址: 0x08<br/>复位值: 0x0000 0000
+
+![image-20220613202916591](pl_reference_mannual.assets/encoder_cdivrx.svg)
+
+| **Field**       | **Description**                                              |
+| :-------------- | :----------------------------------------------------------- |
+| 位31:0 **CDIV** | 相机触发分频值<br />    写入数据后编码和分频控制器自动清除缓存并应用新的数值 <br />    注意：0表示不间断触发，即PL端每个时钟周期均触发相机 |
+
+#### ENCODER寄存器映射
+
+ENCODER寄存器可映射为32位可寻址寄存器，如下表所述：
+
+![encoder_regs](pl_reference_mannual.assets/encoder_regs.svg)
+

doc/version

@@ -0,0 +1 @@
+1.6