ExternalVendorCode/openwifi
1
0
Fork 0
mirror of https://github.com/open-sdr/openwifi.git synced 2024-12-18 21:28:07 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update kuiper README and document

Browse Source
This commit is contained in:
Xianjun Jiao 2023-01-17 14:38:31 +01:00
parent 6a4d7cea87
commit ef526178fb
2 changed files with 207 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
README.md
View File

@ -132,24 +132,19 @@ The board actually is an Linux/Ubuntu computer which is running **hostapd** to o
Since the pre-built SD card image might not have the latest bug-fixes/updates, it is recommended to always copy the latest files in the [user_space](./user_space) directory on to the board. Then update the fpga bitstream and driver (see next section) on to the board.
- Install Vivado/SDK 2018.3 (Vivado Design Suite - HLx Editions - 2018.3 Full Product Installation. If you don't need to generate new FPGA bitstream, WebPack version without license is enough)
- Install Vivado 2021.1. Make sure install Vitis as well. You should have this directory: your_Xilinx_install_directory/Vitis (NOT Vitis_HLS!)
- If the Vitis is not installed, you can add it by running "Xilinx Design Tools --> Add Design Tools for Devices 2021.1" from Xilinx program group/menu in your OS start menu.
- Setup environment variables (use absolute path):
```
export XILINX_DIR=your_Xilinx_install_directory
(Example: export XILINX_DIR=/opt/Xilinx. The Xilinx directory should include sth like: Downloads, SDK, Vivado, xic)
(Example: export XILINX_DIR=/opt/Xilinx. The Xilinx directory should include sth like: Downloads, Vitis, etc.)
export OPENWIFI_HW_DIR=your_openwifi-hw_directory
(The directory where you store the open-sdr/openwifi-hw repo via git clone)
export BOARD_NAME=your_board_name
```
- Pick the FPGA bitstream from openwifi-hw, and generate BOOT.BIN and transfer it on board via ssh channel:
```
For Zynq 7000:
cd openwifi/user_space; ./boot_bin_gen.sh $OPENWIFI_HW_DIR $XILINX_DIR $BOARD_NAME
For Zynq MPSoC (like zcu102 board):
cd openwifi/user_space; ./boot_bin_gen_zynqmp.sh $OPENWIFI_HW_DIR $XILINX_DIR $BOARD_NAME
cd openwifi/user_space; ./boot_bin_gen.sh $XILINX_DIR $BOARD_NAME $OPENWIFI_HW_DIR/boards/$BOARD_NAME/sdk/system_top.xsa
cd openwifi/kernel_boot/boards/$BOARD_NAME/output_boot_bin; scp ./BOOT.BIN root@192.168.10.122:
```
- On board: Put the BOOT.BIN into the BOOT partition.
@ -173,9 +168,10 @@ Since the pre-built SD card image might not have the latest bug-fixes/updates, i
- Prepare Analog Devices Linux kernel source code (only need to run once):
```
cd openwifi/user_space; ./prepare_kernel.sh $XILINX_DIR ARCH_BIT build
cd openwifi/user_space; ./prepare_kernel.sh $XILINX_DIR ARCH_BIT
(For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64)
```
**Note**: You might need to install "flex/bison/libssl-dev" packages via "apt install" to compile the kernel/modules.
**Note**: In Ubuntu, gcc-10 might have issue ('yylloc' error), so use gcc-9 if you encounter error.
- Compile the latest openwifi driver
```
@ -190,7 +186,8 @@ Since the pre-built SD card image might not have the latest bug-fixes/updates, i
Now you can use **wgd.sh** on board to load the new openwifi driver. **wgd.sh** also tries to reload FPGA img if system_top.bit.bin presents in the same directory.
Find more information in [Driver and FPGA dynamic reloading app note](./doc/app_notes/drv_fpga_dynamic_loading.md).
**Note**: If you have symbol or version error while loadng the driver, it could be because the kernel in the SD card image is too old. In this case, you need to follow [[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] to generate your new SD card image.
**Note**: If you have symbol or version error while loadng the driver, it could be because the kernel in the SD card image is too old. In this case, you need put the linux
kernel image generated by prepare_kernel.sh (check [[Update Driver](#Update-Driver)]) to the BOOT partition of SD card. The kernel image file name: adi-linux/arch/arm/boot/uImage (32bit); adi-linux-64/arch/arm64/boot/Image (64bit).
## Update sdrctl
- Copy the sdrctl source files to the board via ssh channel
@ -218,45 +215,7 @@ Since the pre-built SD card image might not have the latest bug-fixes/updates, i
- Input password "openwifi"
## Build openwifi Linux img from scratch
- Install the devicetree compiler -- dtc. (For Ubuntu: sudo apt install device-tree-compiler)
- Install the mkimage tool. (For Ubuntu: sudo apt install u-boot-tools)
- Download [2019_R1-2020_06_22.img.xz](http://swdownloads.analog.com/cse/2019_R1-2020_06_22.img.xz) from [Analog Devices Wiki](https://wiki.analog.com/resources/tools-software/linux-software/zynq_images). Burn it to a SD card.
- Insert the SD card to your Linux PC. Find out the mount point (that has two sub directories BOOT and rootfs), and setup environment variables (use absolute path):
```
export SDCARD_DIR=sdcard_mount_point
export XILINX_DIR=your_Xilinx_install_directory
export OPENWIFI_HW_DIR=your_openwifi-hw_directory
export BOARD_NAME=your_board_name
```
- Run script to update SD card:
```
cd openwifi/user_space; ./update_sdcard.sh $OPENWIFI_HW_DIR $XILINX_DIR $BOARD_NAME $SDCARD_DIR
```
- Config your board to SD card boot mode (check the board manual). Insert the SD card to the board. Power on.
- Login to the board from your PC (PC Ethernet should have IP 192.168.10.1) with one time password **analog**.
```
ssh root@192.168.10.122
```
- Setup routing/NAT **on the PC** for your board -- this internet connection is **important** for post installation/config.
```
sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o NICY -j MASQUERADE
sudo ip route add 192.168.13.0/24 via 192.168.10.122 dev ethX
```
**ethX** is the PC NIC name connecting the board ethernet. **NICY** is the PC NIC name connecting internet (WiFi or another ethernet).
If you want, uncommenting "net.ipv4.ip_forward=1" in /etc/sysctl.conf to make IP forwarding persistent on PC.
- Test the connectivity. Run on board (in the ssh session):
```
route add default gw 192.168.10.1
ping IP_YOU_KNOW_ON_YOUR_NETWORK
```
If there is issue with the connectivity (ping can not reach the target), it needs to be solved before going to the next step.
- Run **one time** script on board to complete post installation/config (After this, password becomes **openwifi**)
```
cd ~/openwifi && ./post_config.sh
```
- Now you can start from [Quick start](#Quick-start) (Skip the image download and burn step)
- For the latest ADI Kuiper image, please check [kuiper.md](./doc/img_build_instruction/kuiper.md)
## Special note for 11b
@ -273,13 +232,13 @@ cd openwifi/user_space; ./build_wpa_supplicant_wo11b.sh
```
## Porting guide
This section explains the porting work by showing the differences between openwifi and Analog Devices reference design. openwifi is based on 2019_R1 of [HDL Reference Designs](https://github.com/analogdevicesinc/hdl).
This section explains the porting work by showing the differences between openwifi and Analog Devices reference design. openwifi is based on 2021_r1 of [HDL Reference Designs](https://github.com/analogdevicesinc/hdl).
- Open the fmcomms2 + zc706 reference design at hdl/projects/fmcomms2/zc706 (Please read Analog Devices help)
- Open the openwifi design zc706_fmcs2 at openwifi-hw/boards/zc706_fmcs2 (Please read openwifi-hw repository)
- "Open Block Design", you will see the differences between openwifi and the reference design. Both in "diagram" and in "Address Editor".
- The address/interrupts of FPGA blocks hooked to the ARM bus should be put/aligned to the devicetree file openwifi/kernel_boot/boards/zc706_fmcs2/devicetree.dts. Linux will parse the devicetree.dtb when booting to know information of attached device (FPGA blocks in our case).
- We use dtc command to get devicetree.dts converted from devicetree.dtb in [Analog Devices Linux image](https://wiki.analog.com/resources/tools-software/linux-software/zynq_images), then do modification according to what we have added/modified to the reference design.
- Please learn the script in [[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] to understand how we generate devicetree.dtb, BOOT.BIN and Linux kernel uImage and put them together to build the full SD card image.
- Please learn the script in [[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] to understand how we generate devicetree.dtb, BOOT.BIN, Linux kernel and put them together to build the full SD card image.
## License

196
doc/img_build_instruction/kuiper.md Normal file
View File

@ -0,0 +1,196 @@
**IMPORTANT pre-conditions**:
- Install Vivado 2021.1. Make sure install Vitis as well. You should have this directory: your_Xilinx_install_directory/Vitis (NOT Vitis_HLS!)
- If the Vitis is not installed, you can add it by running "Xilinx Design Tools --> Add Design Tools for Devices 2021.1" from Xilinx program group/menu in your OS start menu, or Help menu of Vivado.
- SD card at least with 16GB
- Install the devicetree compiler -- dtc. (For Ubuntu: sudo apt install device-tree-compiler)
- Install the mkimage tool. (For Ubuntu: sudo apt install u-boot-tools)
[[Use openwifi prebuilt img](#Use-openwifi-prebuilt-img)]
[[Build SD card from scratch](#Build-SD-card-from-scratch)]
[[Use existing SD card on new board](#Use-existing-SD-card-on-new-board)]
## Use openwifi prebuilt img
Download openwifi pre-built img, such as openwifi-xyz.img.xz, and extract it to .img file.
Use dd command to flash the SD card. (Other software seems having issue!)
```
sudo dd bs=512 count=31116288 if=openwifi-xyz.img of=/dev/your_sdcard_dev
```
(To have correct count value, better to check the .img file actual situation by "fdisk -l img_filename".
## Build SD card from scratch
Download image_2022-08-04-ADI-Kuiper-full.zip from https://wiki.analog.com/resources/tools-software/linux-software/kuiper-linux?redirect=1
Extract it to .img file.
Use dd command to flash the SD card. (Other software seems having issue!)
```
sudo dd bs=512 count=24018944 if=2022-08-04-ADI-Kuiper-full.img of=/dev/your_sdcard_dev
```
(To have correct count value, better to check the .img file actual situation by "fdisk -l img_filename". While making .img from SD card, check the SD card dev instead)
Mount the BOOT and rootfs partition of SD card to your computer.
Change the SD card file: Add following into rootfs/etc/network/interfaces
```
# The loopback interface
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet static
#your static IP
address 192.168.10.122
#your gateway IP
gateway 192.168.10.1
netmask 255.255.255.0
#your network address "family"
network 192.168.10.0
broadcast 192.168.10.255
```
Change the SD card file: Add following into rootfs/etc/sysctl.conf
```
net.ipv4.ip_forward=1
```
Change the SD card file: Add following into rootfs/etc/systemd/system.conf
```
DefaultTimeoutStopSec=2s
```
Put the openwifi/kernel_boot/10-network-device.rules into rootfs/etc/udev/rules.d/
Build and put the following 3 files to the BOOT partition of the SD card:
- Linux kernel image file (check how to generate it by prepare_kernel.sh in [Update Driver](../../README.md#Update-Driver)):
- adi-linux-64/arch/arm64/boot/Image (64bit)
- adi-linux/arch/arm/boot/uImage (32bit)
- devicetree file:
- openwifi/kernel_boot/boards/zcu102_fmcs2/system.dtb (64bit)
- openwifi/kernel_boot/boards/$BOARD_NAME/devicetree.dtb (32bit)
- BOOT.BIN (check how to generate it by boot_bin_gen.sh in [Update FPGA](../../README.md#Update-FPGA)):
- openwifi/kernel_boot/boards/$BOARD_NAME/output_boot_bin/BOOT.BIN
Build openwifi driver according to [Update Driver](../../README.md#Update-Driver)). No need to copy them onboard at this moment.
Create /root/openwifi directory in the rootfs partition of the SD card, and put all files in openwifi/user_space to that directory.
Power on the board with the SD card, connect the board to your host PC (static IP 192.168.10.1) via ethernet, and ssh to the board with password "analog"
```
ssh root@192.168.10.122
```
Then change password to "openwifi" via "passwd" command onbard.
Enlarge the onboard SD disk space, and reboot (https://github.com/analogdevicesinc/adi-kuiper-gen/releases)
```
raspi-config --expand-rootfs
reboot now
```
(You should already build Linux kernel and openwifi driver in previous steps!)
Transfer the kernel modules .ko and openwifi driver .ko onto the board:
```
cd openwifi/user_space
./transfer_driver_userspace_to_board.sh
./transfer_kernel_image_module_to_board.sh $LINUX_KERNEL_SRC $BOARD_NAME
($LINUX_KERNEL_SRC is the directory openwifi/adi-linux-64 or adi-linux)
```
In the ssh session onboard:
```
cd /root
sync
tar -zxvf openwifi.tar.gz
./populate_kernel_image_module_reboot.sh
reboot now
```
Setup routing/NAT **on the PC** for your board -- this internet connection is **important** for post installation/config.
```
sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -o NICY -j MASQUERADE
sudo ip route add 192.168.13.0/24 via 192.168.10.122 dev ethX
```
**ethX** is the PC NIC name connecting the board ethernet. **NICY** is the PC NIC name connecting internet (WiFi or another ethernet).
If you want, uncommenting "net.ipv4.ip_forward=1" in /etc/sysctl.conf to make IP forwarding persistent on PC.
Test the connectivity. Run on board (in the ssh session):
```
route add default gw 192.168.10.1
ping IP_YOU_KNOW_ON_YOUR_NETWORK
```
If there is issue with the connectivity (ping can not reach the target), it needs to be solved before going to the next step.
Do misc configurations/installations in the ssh session onboard:
```
cd /root/openwifi
route add default gw 192.168.10.1 || true
ping google.com
sudo apt update
chmod +x *.sh
# build sdrctl and inject_80211
sudo apt-get -y install libnl-3-dev
sudo apt-get -y install libnl-genl-3-dev
cd sdrctl_src
make
cp sdrctl ../
cd ../side_ch_ctl_src/
gcc -o side_ch_ctl side_ch_ctl.c
cp side_ch_ctl ../
cd ..
cd ./inject_80211/
make
cd ..
# install and setup dhcp server
sudo apt-get -y install isc-dhcp-server
cp dhcpd.conf /etc/dhcp/dhcpd.conf
# install hostapd and other useful tools
sudo apt-get -y install hostapd
sudo apt-get -y install tcpdump
sudo apt-get -y install webfs
sudo apt-get -y install iperf
sudo apt-get -y install iperf3
sudo apt-get -y install libpcap-dev
sudo apt-get -y install bridge-utils
# add video file into the onbard web server
wget -P webserver/ https://users.ugent.be/~xjiao/openwifi-low-aac.mp4
```
Run openwifi in the ssh session onboard:
```
cd /root/openwifi
./wgd.sh
iwlist sdr0 scan
./fosdem.sh
```
## Use existing SD card on new board
You don't need to do it from scratch on a blank SD card. Instead, you can start from existing SD card (for example zcu102), and use it for a new board (for example zedboard).
1. Do this section (see above) "Build and put the following 3 files to the BOOT partition of the SD card" for the new board by replacing the file on the existing SD card.
2. Build openwifi driver according to [Update Driver](../../README.md#Update-Driver)). No need to copy them onboard at this moment.
3. Use the existing SD card to boot the new board.
4. Do this section (see above) "Transfer the kernel modules .ko and openwifi driver .ko onto the board". Do not forget the operations onboard after the file transfer:
```
cd /root
sync
tar -zxvf openwifi.tar.gz
./populate_kernel_image_module_reboot.sh
reboot now
```