xref: /openwifi/doc/app_notes/drv_fpga_dynamic_loading.md (revision 7eea29887ac31c48428f5ca2004418fc9511987e) 
1The **wgd.sh** (running on board) supports reloading driver and/or FPGA image dynamically without rebooting/power-cycle. It can work in a
2flexible way.
3
4The purpose of this feature is to help you easily reload driver and FPGA built from your branch/version/variant/modification, and switch/run different driver and FPGA of different branch/version/variant/modification without rebooting. To enjoy this feature, always ensure your onboard openwifi/files are the latest files in [user_space](../../user_space)).
5
6- [[Reload driver only](#Reload-driver-only)]
7- [[Reload driver and FPGA](#Reload-driver-and-FPGA)]
8- [[Reload driver and FPGA in target directory](#Reload-driver-and-FPGA-in-target-directory)]
9- [[Reload driver and FPGA from a single package file](#Reload-driver-and-FPGA-from-a-single-package-file)] -- **RECOMMENDED!**
10- [[Suggested practice to generate driver FPGA variants](#Suggested-practice-to-generate-driver-FPGA-variants)]
11- [[Detailed full usage info](#Detailed-full-usage-info)]
12
13Note: Make sure you have compiled driver before. Check [Update Driver](../../README.md#update-driver).
14
15## Reload driver only
16This is the original way. To let **wgd.sh** only loads the driver without touching FPGA, please ensure FPGA image file **system_top.bit.bin** is **NOT**
17present in the directory. If wgd.sh can not find the FPGA image, it will skip reloading it.
18
19## Reload driver and FPGA
20- Generate the reloadable FPGA file **system_top.bit.bin**. In the Linux host computer:
21  ```
22  cd openwifi/user_space
23  ./drv_and_fpga_package_gen.sh $OPENWIFI_HW_IMG_DIR $XILINX_DIR $BOARD_NAME
24  ```
25  Then **system_top.bit.bin** will be generated in openwifi/user_space.
26
27- Put **system_top.bit.bin** on board in the same directory as wgd.sh and other driver files (.ko)
28- Run **wgd.sh** on board as usual
29
30## Reload driver and FPGA in target directory
31Put **system_top.bit.bin** on board together with other driver files (.ko) in a directory ($TARGET_DIR), then run on board:
32```
33./wgd.sh $TARGET_DIR
34```
35In this way, different versions/variants of driver/FPGA can be put in different directories. Then **wgd.sh** can be used to switch
36between them without rebooting/power-cycle.
37
38## Reload driver and FPGA from a single package file
39The openwifi/user_space/**drv_and_fpga_package_gen.sh** also generates a single package file **drv_and_fpga.tar.gz**, which includes driver files (.ko),
40FPGA image and many other source files with rich infos that are related.
41
42You can switch to your own branch/version/variant, build the single package file via **drv_and_fpga_package_gen.sh**, rename it with a more meaningful name (such as add version or variant info as postfix), put the renamed **drv_and_fpga_MEANINGFUL_POSTFIX.tar.gz** on board in the same directory as **wgd.sh**, and let **wgd.sh** load it:
43```
44./wgd.sh ./drv_and_fpga_MEANINGFUL_POSTFIX.tar.gz
45```
46In this way, different version/variants of driver/FPGA can be switched by **wgd.sh** without rebooting/power-cycle.
47
48## Suggested practice to generate driver FPGA variants
49There are several ways to generate variants of the single driver-FPGA package file. For example:
50
51- Switch/create another branch for openwifi and openwifi-hw, work/modify there, then generate the single package file via **drv_and_fpga_package_gen.sh**. This package is the branch specific, so renaming the package name to a more meaningful one would be good practice.
52- In the same branch, set different arguments (finally macro definitions in .h and .v files) via conditional compiling to enable/disable different driver and FPGA code blocks/functionalities, then generate the single package file via **drv_and_fpga_package_gen.sh**. Rename the package to remind you which conditions are ON/OFF.
53    - Check "Conditional compile by verilog macro" in openwifi-hw README for FPGA design
54    - Input more arguments (max 5) to driver building script "make_all.sh $XILINX_DIR ARCH_BIT". Those arguments will be converted to "#define argument" in pre_def.h for driver conditional compiling. **Attention:** **drv_and_fpga_package_gen.sh** currently only call **make_all.sh** without extra arguments. If you have conditional compiling arguments, do not forget to put them into **drv_and_fpga_package_gen.sh** as extra arguments of **make_all.sh**.
55
56## Detailed full usage info
57Run the "./wgd.sh -h" on board or open wgd.sh to see full usage info:
58```
59usage:
60  Script for load (or download+load) different driver and FPGA img without rebooting
61  no  argument: Load .ko driver files and FPGA img (if system_top.bit.bin exist) in current dir with test_mode=0.
62  1st argument: If it is a NUMBER, it will be assigned to test_mode. Then load everything from current dir.
63  1st argument: If it is a string called "remote", it will download driver/FPGA and load everything.
64  - 2nd argument (if exist) is the target directory name for downloading and reloading
65  - 3rd argument (if exist) is the value for test_mode
66  1st argument: neither NUMBER nor "remote" nor a .tar.gz file, it is regarded as a directory and load everything from it.
67  - 2nd argument (if exist) is the value for test_mode
68  1st argument: a .tar.gz file, it will be unpacked then load from that unpacked directory
69  - 2nd argument (if exist) is the value for test_mode
70```
71