From d78b4e137eca06f0a007f155880b2ccce309785f Mon Sep 17 00:00:00 2001 From: chenmiao Date: Tue, 2 Sep 2025 09:06:53 +0000 Subject: [PATCH] refactor: Reorganize project directory structure - Restructured documentation files into logical directories: * Moved tutorials and docs to pages/ with topic-based subdirectories * Consolidated platform docs under pages/platforms/ * Organized toolchain docs under pages/toolchains/ - Unified resource files under resource/ directory: * Board-specific resources moved to resource/de0_nano/ * Simulator configs moved to resource/or1ksim/ * All images centralized in resource/images/ - Updated _config.yml and index.md to reflect new structure This restructuring improves project maintainability and document discoverability by establishing a clearer and more logical file organization. Signed-off-by: chenmiao --- _config.yml | 5 ++++- de0_nano/.gitignore | 3 --- index.md | 14 +++++++------- tutorials.md => pages/futher_reading.md | 0 {docs => pages/linux}/linux-on-or1ksim.md | 0 {docs => pages/linux}/linux-on-qemu.md | 0 docs/Linux.md => pages/linux/linux.md | 2 +- docs/Debugging.md => pages/platforms/debugging.md | 0 fusesoc.md => pages/platforms/fusesoc.md | 2 +- .../platforms/fusesoc/de0_nano.md | 8 ++++---- or1ksim/index.md => pages/platforms/or1ksim.md | 8 ++++---- platforms.md => pages/platforms/platforms.md | 0 {platform => pages/platforms}/qemu.md | 0 images.md => pages/quick_start.md | 0 glibc.md => pages/toolchains/glibc.md | 0 musl.md => pages/toolchains/musl.md | 0 newlib.md => pages/toolchains/newlib.md | 0 toolchains.md => pages/toolchains/toolchains.md | 0 or1k-dev.tcl => resource/de0_nano/or1k-dev.tcl | 0 {sw => resource/de0_nano/sw}/hello/hello.c | 0 {sw => resource/de0_nano/sw}/timer/timer.c | 0 .../images}/hello-initramfs-host.png | Bin .../images}/hello-initramfs-qemu.png | Bin .../images}/qemu-bootup-output.png | Bin {de0_nano/doc => resource/images}/uart.png | Bin {or1ksim => resource/or1ksim}/Makefile | 0 {or1ksim => resource/or1ksim}/or1ksim.cfg | 0 {platform => resource/platform}/hello.c | 0 28 files changed, 21 insertions(+), 21 deletions(-) delete mode 100644 de0_nano/.gitignore rename tutorials.md => pages/futher_reading.md (100%) rename {docs => pages/linux}/linux-on-or1ksim.md (100%) rename {docs => pages/linux}/linux-on-qemu.md (100%) rename docs/Linux.md => pages/linux/linux.md (96%) rename docs/Debugging.md => pages/platforms/debugging.md (100%) rename fusesoc.md => pages/platforms/fusesoc.md (95%) rename de0_nano/index.md => pages/platforms/fusesoc/de0_nano.md (91%) rename or1ksim/index.md => pages/platforms/or1ksim.md (95%) rename platforms.md => pages/platforms/platforms.md (100%) rename {platform => pages/platforms}/qemu.md (100%) rename images.md => pages/quick_start.md (100%) rename glibc.md => pages/toolchains/glibc.md (100%) rename musl.md => pages/toolchains/musl.md (100%) rename newlib.md => pages/toolchains/newlib.md (100%) rename toolchains.md => pages/toolchains/toolchains.md (100%) rename or1k-dev.tcl => resource/de0_nano/or1k-dev.tcl (100%) rename {sw => resource/de0_nano/sw}/hello/hello.c (100%) rename {sw => resource/de0_nano/sw}/timer/timer.c (100%) rename {platform/resources => resource/images}/hello-initramfs-host.png (100%) rename {platform/resources => resource/images}/hello-initramfs-qemu.png (100%) rename {platform/resources => resource/images}/qemu-bootup-output.png (100%) rename {de0_nano/doc => resource/images}/uart.png (100%) rename {or1ksim => resource/or1ksim}/Makefile (100%) rename {or1ksim => resource/or1ksim}/or1ksim.cfg (100%) rename {platform => resource/platform}/hello.c (100%) diff --git a/_config.yml b/_config.yml index d3f087d..9d5a69e 100644 --- a/_config.yml +++ b/_config.yml @@ -3,4 +3,7 @@ theme: just-the-docs color_scheme: or1k repository: openrisc/tutorials -include: ['debugging', 'de0_nano', 'docs', 'or1ksim', 'platform', 'sw'] +include: [ + 'pages', + 'resouce', +] diff --git a/de0_nano/.gitignore b/de0_nano/.gitignore deleted file mode 100644 index 5a8ceab..0000000 --- a/de0_nano/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -build/ -fusesoc.log -*.elf diff --git a/index.md b/index.md index 8e2c021..9d55837 100644 --- a/index.md +++ b/index.md @@ -78,8 +78,8 @@ or1k_interrupts_disable(void) } ``` -See the [newlib tutorial](newlib.html) for details on how to setup the newlib development -environment. Or checkout the [Quickstart tutorial](images.html) for docker images +See the [newlib tutorial](./pages/toolchains/newlib.html) for details on how to setup the newlib development +environment. Or checkout the [Quickstart tutorial](./pages/quick_start.html) for docker images that have the newlib environment out of the box. ## Tools (partially required) @@ -92,8 +92,8 @@ OpenRISC. You can install it as described Featured in: - * [De0 Nano](de0_nano/) - De0 Nano FPGA development board platform tutorial. - * [Quickstart Images](images.html) - Docker verilog development environment + * [De0 Nano](./pages/platforms/fusesoc/) - De0 Nano FPGA development board platform tutorial. + * [Quickstart Images](./pages/quick_start.html) - Docker verilog development environment ### OpenOCD @@ -103,8 +103,8 @@ install a current version. Featured in: - * [De0 Nano](de0_nano/) - De0 Nano FPGA development board platform tutorial. - * [Debugging](docs/Debugging.html) - OpenOCD debugging cheat sheet. + * [De0 Nano](./pages/platforms/fusesoc/) - De0 Nano FPGA development board platform tutorial. + * [Debugging](./pages/platforms/debugging.html) - OpenOCD debugging cheat sheet. ### Quartus Prime @@ -115,7 +115,7 @@ required for some tutorials. Featured in: - * [De0 Nano](de0_nano/) - De0 Nano FPGA development board platform tutorial. + * [De0 Nano](./pages/platforms/fusesoc/) - De0 Nano FPGA development board platform tutorial. For downloading the free version, visit the [Intel website](https://www.intel.com/content/www/us/en/software-kit/849769/intel-quartus-prime-lite-edition-design-software-version-24-1-for-linux.html) and diff --git a/tutorials.md b/pages/futher_reading.md similarity index 100% rename from tutorials.md rename to pages/futher_reading.md diff --git a/docs/linux-on-or1ksim.md b/pages/linux/linux-on-or1ksim.md similarity index 100% rename from docs/linux-on-or1ksim.md rename to pages/linux/linux-on-or1ksim.md diff --git a/docs/linux-on-qemu.md b/pages/linux/linux-on-qemu.md similarity index 100% rename from docs/linux-on-qemu.md rename to pages/linux/linux-on-qemu.md diff --git a/docs/Linux.md b/pages/linux/linux.md similarity index 96% rename from docs/Linux.md rename to pages/linux/linux.md index 66a1178..ae55236 100644 --- a/docs/Linux.md +++ b/pages/linux/linux.md @@ -76,5 +76,5 @@ halt; load_image vmlinux; reg r3 0; reg npc 0x100; resume The kernel image is now available as an elf file called `vmlinux`. This file can be used as any other bare-metal program for OpenRISC. To test the Linux image, you can: * Run it in the reference C simulator (or1ksim) * Run it on a simulated RTL model (Most likely extremely slow, unless using verilator) -* [Load it to RAM on an FPGA board with a debugger](Debugging.html) +* [Load it to RAM on an FPGA board with a debugger](../platforms/debugging.html) * Program it to non-volatile flash on an FPGA board diff --git a/docs/Debugging.md b/pages/platforms/debugging.md similarity index 100% rename from docs/Debugging.md rename to pages/platforms/debugging.md diff --git a/fusesoc.md b/pages/platforms/fusesoc.md similarity index 95% rename from fusesoc.md rename to pages/platforms/fusesoc.md index 0123719..0b8609f 100644 --- a/fusesoc.md +++ b/pages/platforms/fusesoc.md @@ -7,7 +7,7 @@ parent: Platforms The FuseSoC build system, dependency manager and fpga integration platform allows for easy creation of OpenRISC systems. If is featured in our -[Quick Start with Docker Images](images/) as our main fpga development +[Quick Start with Docker Images](../quick_start.html) as our main fpga development platform. For in depth documentation see: * [FuseSoC Manual](https://fusesoc.readthedocs.io/en/stable/index.html) - Full documentation. diff --git a/de0_nano/index.md b/pages/platforms/fusesoc/de0_nano.md similarity index 91% rename from de0_nano/index.md rename to pages/platforms/fusesoc/de0_nano.md index 72986fb..e45e167 100644 --- a/de0_nano/index.md +++ b/pages/platforms/fusesoc/de0_nano.md @@ -13,12 +13,12 @@ parent: FuseSoC * OpenOCD * The quartus FPGA design software * `fusesoc` - The [FuseSoC build system](../fusesoc.html). - * `or1k-elf-` Toolchain as installed in our [newlib tutorial](../newlib.html). + * `or1k-elf-` Toolchain as installed in our [newlib tutorial](../../toolchains/newlib.html). #### Files - * [hello.c](../sw/hello/hello.c) - A Hello World test program. - * [timer.c](../sw/timer/timer.c) - A baremetal example using the OpenRISC timer api's provided by newlib. + * [hello.c](../../../resource/de0_nano/sw/hello/hello.c) - A Hello World test program. + * [timer.c](../../../resource/de0_nano/sw/timer/timer.c) - A baremetal example using the OpenRISC timer api's provided by newlib. ## DE0 Nano @@ -46,7 +46,7 @@ computer. If you want to use UART, an extra dongle is needed. Any USB-UART adapter can be used. You need to connect it to the header on the bottom of the board as depicted below. -![uart](doc/uart.png "Connect UART to board") +![uart](../../../resource/images/uart.png "Connect UART to board") ### Setup the Environment diff --git a/or1ksim/index.md b/pages/platforms/or1ksim.md similarity index 95% rename from or1ksim/index.md rename to pages/platforms/or1ksim.md index 7f6e203..a4b5a65 100644 --- a/or1ksim/index.md +++ b/pages/platforms/or1ksim.md @@ -16,9 +16,9 @@ nav_order: 2 We will download these below. - - [or1ksim.cfg](or1ksim.cfg) - config needed for or1ksim - - [hello.c](../sw/hello/hello.c) - hello world program - - [timer.c](../sw/timer/timer.c) - timer program + - [or1ksim.cfg](../../resouce/or1ksim/or1ksim.cfg) - config needed for or1ksim + - [hello.c](../../resouce/de0_nano/sw/hello/hello.c) - hello world program + - [timer.c](../../resouce/de0_nano/sw/timer/timer.c) - timer program - [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz) - The OpenRISC simulator # or1ksim Tutorial @@ -188,7 +188,7 @@ A second elapsed ## Next steps -Also checkout our tutorial on how to run [Linux on or1ksim](../docs/linux-on-or1ksim.html). +Also checkout our tutorial on how to run [Linux on or1ksim](../linux/linux-on-or1ksim.html). ## Further Reading diff --git a/platforms.md b/pages/platforms/platforms.md similarity index 100% rename from platforms.md rename to pages/platforms/platforms.md diff --git a/platform/qemu.md b/pages/platforms/qemu.md similarity index 100% rename from platform/qemu.md rename to pages/platforms/qemu.md diff --git a/images.md b/pages/quick_start.md similarity index 100% rename from images.md rename to pages/quick_start.md diff --git a/glibc.md b/pages/toolchains/glibc.md similarity index 100% rename from glibc.md rename to pages/toolchains/glibc.md diff --git a/musl.md b/pages/toolchains/musl.md similarity index 100% rename from musl.md rename to pages/toolchains/musl.md diff --git a/newlib.md b/pages/toolchains/newlib.md similarity index 100% rename from newlib.md rename to pages/toolchains/newlib.md diff --git a/toolchains.md b/pages/toolchains/toolchains.md similarity index 100% rename from toolchains.md rename to pages/toolchains/toolchains.md diff --git a/or1k-dev.tcl b/resource/de0_nano/or1k-dev.tcl similarity index 100% rename from or1k-dev.tcl rename to resource/de0_nano/or1k-dev.tcl diff --git a/sw/hello/hello.c b/resource/de0_nano/sw/hello/hello.c similarity index 100% rename from sw/hello/hello.c rename to resource/de0_nano/sw/hello/hello.c diff --git a/sw/timer/timer.c b/resource/de0_nano/sw/timer/timer.c similarity index 100% rename from sw/timer/timer.c rename to resource/de0_nano/sw/timer/timer.c diff --git a/platform/resources/hello-initramfs-host.png b/resource/images/hello-initramfs-host.png similarity index 100% rename from platform/resources/hello-initramfs-host.png rename to resource/images/hello-initramfs-host.png diff --git a/platform/resources/hello-initramfs-qemu.png b/resource/images/hello-initramfs-qemu.png similarity index 100% rename from platform/resources/hello-initramfs-qemu.png rename to resource/images/hello-initramfs-qemu.png diff --git a/platform/resources/qemu-bootup-output.png b/resource/images/qemu-bootup-output.png similarity index 100% rename from platform/resources/qemu-bootup-output.png rename to resource/images/qemu-bootup-output.png diff --git a/de0_nano/doc/uart.png b/resource/images/uart.png similarity index 100% rename from de0_nano/doc/uart.png rename to resource/images/uart.png diff --git a/or1ksim/Makefile b/resource/or1ksim/Makefile similarity index 100% rename from or1ksim/Makefile rename to resource/or1ksim/Makefile diff --git a/or1ksim/or1ksim.cfg b/resource/or1ksim/or1ksim.cfg similarity index 100% rename from or1ksim/or1ksim.cfg rename to resource/or1ksim/or1ksim.cfg diff --git a/platform/hello.c b/resource/platform/hello.c similarity index 100% rename from platform/hello.c rename to resource/platform/hello.c