From e51208cb1f515e43cb69c0838f4ea3dbf08b0e72 Mon Sep 17 00:00:00 2001 From: Max Tyson <98maxt98@gmail.com> Date: Tue, 9 Jan 2024 11:43:47 +1300 Subject: [PATCH] Update Readme (#6) --- .github/workflows/max-os.yml | 3 +- docs/LICENSE => LICENSE | 0 README.md | 379 +++++++++++------- .../Boot/{Console v2.png => Console_v2.png} | Bin 4 files changed, 231 insertions(+), 151 deletions(-) rename docs/LICENSE => LICENSE (100%) rename docs/Screenshots/Boot/{Console v2.png => Console_v2.png} (100%) diff --git a/.github/workflows/max-os.yml b/.github/workflows/max-os.yml index 228b70b7..fe3b7b32 100644 --- a/.github/workflows/max-os.yml +++ b/.github/workflows/max-os.yml @@ -56,7 +56,8 @@ jobs: # The type of runner that the job will run on runs-on: ubuntu-20.04 - # Steps represent a sequence of tasks that will be executed as part of the job + # Dont generate docs on dev branch + if: github.ref == 'refs/heads/main' steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 diff --git a/docs/LICENSE b/LICENSE similarity index 100% rename from docs/LICENSE rename to LICENSE diff --git a/README.md b/README.md index d1be2757..d5744fee 100644 --- a/README.md +++ b/README.md @@ -1,163 +1,242 @@ + + + + + + + + +[![Contributors][contributors-shield]][contributors-url] +[![Forks][forks-shield]][forks-url] +[![Stargazers][stars-shield]][stars-url] +[![Issues][issues-shield]][issues-url] +[![Build][built-shield]][built-url] + + +
+
+ + Logo + + +

Max OS

+ +

+ A 32bit hobby operating system written in C++ +
+ Explore the docs » +
+
+ View Demo + · + Report Bug + · + Request Feature +

+
+ + + + +
+ Table of Contents +
    +
  1. + About The Project +
    2. +
  2. + Getting Started + +
    3. +
  3. Usage
    4. +
  4. Roadmap
    5. +
  5. Contributing
    6. +
  6. License
    7. +
  7. Acknowledgments
    8. +
+
+ + + + +## About The Project + +[![MaxOS][product-screenshot]](#) + +Max OS is a hobby operating system developed for the 32bit platform using C++ and Assembly. The project is currently in the early stages of development and is not yet ready for use. The project is being developed as a learning experience and is not intended to be used as a production operating system. + +Max OS supports device drivers, memory management, multitasking, a GUI, and more. The project is being developed with the goal of being able to run on real hardware, however, it is currently only able to run on a virtual machine. + +

(back to top)

+ + +## Getting Started + +This is how to build the Max OS operating system from source. (Alternatively, you can download the latest built kernel from the workflow artifacts) + +### Prerequisites + +This is the list of required packages to build the operating system from source. (Note the build scripts should install these automatically) +* build-essential +* bison +* flex +* libgmp3-dev +* libmpc-dev +* libmpfr-dev +* texinfo +* libisl-dev +* cmake + ```sh + sudo apt update + sudo apt install -y build-essential bison flex libgmp3-dev libmpc-dev libmpfr-dev texinfo libisl-dev cmake + ``` + +Note: If you want to run the operating system in a virtual machine, you will need to install QEMU. (If in WSL the script will look for a Windows installation of QEMU) +### Installation + +- Upon first build follow steps 1-5 +- If you change the file structure (e.g. add a new file) follow steps 3-5 +- If you running on a new boot (eg you rebooted your computer) follow steps 4-5 +- If you only change a file follow step 5 + +1. Clone the repo + ```sh + git clone https://github.com/maxtyson123/MaxOS.git + cd MaxOS + ``` + +2. Create the cross compiler (This will take a while) + ```sh + cd toolchain + ./make_cross_compiler.sh + cd ../ + ``` + +3. Generate makefiles + ```sh + cd cmake-build + cmake .. -DCMAKE_TOOLCHAIN_FILE=toolchain/CMakeToolchain.txt + ``` + +4. Clean the build directory + ```sh + make clean + ``` + +5. Build the operating system & Run it in QEMU + ```sh + make install image run + ``` -# Max Os +

(back to top)

-Max os is based on: [OS Dev Wiki](https://wiki.osdev.org/Creating_an_Operating_System), [YouTube WYOOS](https://www.youtube.com/watch?v=1rnA6wpF0o4&list=PLHh55M_Kq4OApWScZyPl5HhgsTJS9MZ6M&ab_channel=WriteyourownOperatingSystem'), [KayOS]('#') -This is a hobby OS developed in mainly C++, the aim of this project is to setup a functional operating system that supports programs, has a GUI and is POSIX compatible. -In the future I aim to have it run on a raspberry PI, include its very own in house web browser and a custom game engine. + +## Usage + +No user usage so far (userland will be added in the future) -The codebase is well commented with additional notes in the docs directory. Contribution is welcome, however it would be ideal once the basics are set up and I begin on the extended features. (See projects) +#### Boot Console +![Boot Console](docs/Screenshots/Boot/Console20%v2.png) -(BUGGY) Now with custom build toolchain (binutils, gcc, g++, make, etc) and a custom that can optionally be installed via the make_toolchain.sh file located in toolcahin. The OS can be built using this (build_via_tc.sh) or built via the make file (see below.) The toolchain will become more mainstream with the release of the c libraries. +#### GUI +![GUI](docs/Screenshots/GUI/Windows20%VESA.png) -MaxOS now has support for hardrives (Fat32 filesytem) and can be booted from an ATA drive. The makefile will mount MaxOS onto mnt/maxOS_img_1, however it is not ideal to directly copy files onto the mount point as upon build the folders are wiped and instead you should interact with the folders in the "filesystem" directory. (Note: when you reboot your device you need to run toolchain/create_disk_img.sh to remount the disk) + +## Roadmap -[![wakatime](https://wakatime.com/badge/github/maxtyson123/max-os.svg)](https://wakatime.com/badge/github/maxtyson123/max-os) -![maxOS](https://github.com/maxtyson123/max-os/workflows/maxOS/badge.svg) +- [x] Bootloader +- [x] GDT +- [x] IDT +- [x] Interrupts +- [x] Keyboard & Mouse +- [x] PCI +- [x] ATA +- [x] VESA +- [x] Memory Management +- [x] Multitasking +- [x] GUI +- [x] Window Manager +- [ ] Paging +- [ ] Userspace +- [ ] IPC +- [ ] VFS +- [ ] Loading ELF +- [ ] CLI +- [ ] Porting Libc +- [ ] Userland GUI +- [ ] DOOM Port? - -## Screenshots -Booting -![Screenshot](docs/Screenshots/Boot/Console%20v2.png) cd +See the [open issues](https://github.com/maxtyson123/MaxOS/issues) for a full list of proposed features (and known issues). -GUI Window System -![Screenshot](docs/Screenshots/GUI/Windows%20(VESA).png) +

(back to top)

-### Whats working: -- [x] Bootloader -- [x] Global Descriptor Table -- [x] Interrupt Descriptor Table -- [x] Keyboard and Mouse Drivers -- [x] PCI Communication (for drivers) -- [x] GUI Framework (Front to back drawing, Area invalidation, etc) -- [x] Process Switching / Multitasking -- [x] Memory Management -- [x] Ethernet Networking Drivers -- [x] Various Internet Protocols (ARP, ICMP, UDP, TCP) -- [ ] {FIX Later} Fat32 Filesystem through an ATA driver - - -### Future Plans - -Kernel Cleanup - -- [x] Timer rewrite -- [x] GUI Draw Rewrite -- [x] Console rewrite -- [x] VESA Video Mode -- [x] Kernel Boot Rewrite -- [x] Rewrite Event Handlers -- [x] Cross-Compiler -- [x] Better Scripts -- [x] GUI Bug Fixes -- [x] Better Commenting and Doxygen Documentation -- [x] Use better c++ coding conventions -- [x] CMAKE Build System -- [ ] Clean up all the TODOs & Errors -- [ ] Rewrite Readme - -Road to Userspace pt 1 - kernel core features - -- [ ] New Process Manager / Scheduler -- [ ] Interprocess Communication -- [ ] Might need an I/O Rewrite (more to come) -- [ ] Better Memory Management -- [ ] Paging - ? -- [ ] Filesystem Fixes -- [ ] System Calls - -Road to Userspace pt 2 - kernel supporting features - -- [ ] LibC -- [ ] OS Specific Toolchain -- [ ] Elf Loader -- [ ] Shell -- [ ] Services, (GUI Server, Network Server, etc) -- [ ] More Libraries (LibM, LibNet, LibGUI) - - -OS Functionality -- [ ] ext2 Filesystem -- [ ] GUI Theming, More GUI Widgets -- [ ] Game Ports (DOOM etc..) -- [ ] Users & Privileges -- [ ] Virtual Memory -- [ ] More drivers, essential ones etc, wifi maybe -- [ ] Microkernel -- [ ] 64 Bit -- [ ] 3D Rendering e.g. OpenGL -- [ ] Python Port -- [ ] Game Engine -- [ ] Web Browser -- [ ] M++ -- [ ] VNC - -### Services -Current: -- None - -Planned: -- GUI Server -- Network Server - -### GUI Programs -Current: -- Debug Console - -Planned: -- Telnet Server -### CLI Programs -Current: -- None - -Planned: -- UNIX Shell -### Libraries -Current: -- None - -Planned: -- LibC -- LibM -- LibNet -- LibGUI -### Ports -Current: -- None - -Planned: -- Git -- DOOM -- Bash -## Run Locally - -Steps for linux: - -Clone the project - -```bash - git clone https://github.com/maxtyson123/max-os -``` - -Go to the project directory, fix the scripts (GitHub does weird line endings) - -```bash - cd max-os - toolchain/fix_scripts_github.sh -``` - -Install Dependencies & build - -```bash - make install_dep - make build -``` - -Run Os In Qemu - -```bash -make runQ -``` \ No newline at end of file + +## Contributing + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". +Don't forget to give the project a star! Thanks again! + +1. Fork the Project +2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) +3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the Branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + +

(back to top)

+ + + + +## License + +Distributed under the BSD 3-Clause License. See `LICENSE` for more information. + +

(back to top)

+ + + +## Acknowledgments + +* [OSDev.org](https://wiki.osdev.org/) +* [WYOOS](http://wyoos.org/) +* [OSDev Notes](https://github.com/dreamportdev/Osdev-Notes/) +* [OSDev Subreddit](https://www.reddit.com/r/osdev/) +* [Duck OS](https://github.com/byteduck/duckOS) + +

(back to top)

+ + + + +[product-screenshot]: docs/Screenshots/Boot/Console_v2.png +[contributors-shield]: https://img.shields.io/github/contributors/maxtyson123/MaxOS.svg?style=for-the-badge +[contributors-url]: https://github.com/maxtyson123/MaxOS/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/maxtyson123/MaxOS.svg?style=for-the-badge +[forks-url]: https://github.com/maxtyson123/MaxOS/network/members +[stars-shield]: https://img.shields.io/github/stars/maxtyson123/MaxOS.svg?style=for-the-badge +[stars-url]: https://github.com/maxtyson123/MaxOS/stargazers +[issues-shield]: https://img.shields.io/github/issues/maxtyson123/MaxOS.svg?style=for-the-badge +[issues-url]: https://github.com/maxtyson123/MaxOS/issues +[built-shield]: https://img.shields.io/github/actions/workflow/status/maxtyson123/MaxOS/max-os.yml?style=for-the-badge +[built-url]: https://github.com/maxtyson123/MaxOS/actions/workflows/max-os.yml \ No newline at end of file diff --git a/docs/Screenshots/Boot/Console v2.png b/docs/Screenshots/Boot/Console_v2.png similarity index 100% rename from docs/Screenshots/Boot/Console v2.png rename to docs/Screenshots/Boot/Console_v2.png