diff --git a/.github/workflows/max-os.yml b/.github/workflows/max-os.yml index b2d0d2a1..14e7b890 100644 --- a/.github/workflows/max-os.yml +++ b/.github/workflows/max-os.yml @@ -50,3 +50,25 @@ jobs: with: name: Kernel Binary path: maxOS.bin + + generate-docs: + # 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 + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v2 + + - name: Generate Docs + run: | + make documentation + + - name: Upload to branch + uses: s0/git-publish-subdir-action@develop + env: + REPO: self + BRANCH: docs + FOLDER: docs/doxy + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + MESSAGE: "Build: ({sha}) {msg}" \ No newline at end of file diff --git a/Makefile b/Makefile index 9db825fa..1b106b60 100644 --- a/Makefile +++ b/Makefile @@ -83,15 +83,22 @@ virtualbox: iso .PHONY: clean clean: + # Remove the kernel object files rm -rf obj rm -f maxOS.bin maxOS.sym maxOS.img + # Remove all files and folders in the docs/doxy folder except for the Doxyfile + cd docs/doxy && find . ! -name 'Doxyfile' -type f -exec rm -f {} + + cross_compiler: cd toolchain && ./make_cross_compiler.sh disk_img: cd toolchain && ./create_disk_img.sh +documentation: + cd toolchain && ./make_documentation.sh + install_deps: sudo apt-get update -y sudo apt-get install -y grub-pc qemu-system-i386 gdb dosfstools bridge-utils xorriso diff --git a/docs/Screenshots/Logo.png b/docs/Screenshots/Logo.png new file mode 100644 index 00000000..439a5838 Binary files /dev/null and b/docs/Screenshots/Logo.png differ diff --git a/docs/doxy/Doxyfile b/docs/doxy/Doxyfile new file mode 100644 index 00000000..3530a919 --- /dev/null +++ b/docs/doxy/Doxyfile @@ -0,0 +1,275 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Max OS" +PROJECT_NUMBER = 0.1 +PROJECT_LOGO = ./Logo.png +OUTPUT_DIRECTORY = . +CREATE_SUBDIRS = NO +CREATE_SUBDIRS_LEVEL = 8 +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +RESOLVE_UNNAMED_PARAMS = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_HEADERFILE = YES +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LINE_FORMAT = "at line $line of file $file" +INPUT = ../../kernel +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cxxm \ + *.cpp \ + *.cppm \ + *.ccm \ + *.c++ \ + *.c++m \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.ixx \ + *.l \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f18 \ + *.f \ + *.for \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf \ + *.ice +RECURSIVE = YES +EXCLUDE_SYMLINKS = NO +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +FILTER_SOURCE_FILES = NO +SOURCE_BROWSER = YES +INLINE_SOURCES = YES +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_ADD_INC_PATHS = YES +ALPHABETICAL_INDEX = YES +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = header.html +HTML_EXTRA_STYLESHEET = ./doxygen-awesome.css +HTML_EXTRA_FILES = ./doxygen-awesome-paragraph-link.js \ + ./doxygen-awesome-darkmode-toggle.js \ + ./doxygen-awesome-interactive-toc.js +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = YES +FULL_SIDEBAR = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +OBFUSCATE_EMAILS = YES +HTML_FORMULA_FORMAT = png +FORMULA_FONTSIZE = 10 +USE_MATHJAX = NO +MATHJAX_VERSION = MathJax_2 +MATHJAX_FORMAT = HTML-CSS +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHDATA_FILE = searchdata.xml +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +MAKEINDEX_CMD_NAME = makeindex +LATEX_MAKEINDEX_CMD = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_BIB_STYLE = plain +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +GENERATE_XML = NO +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +XML_NS_MEMB_FILE_SCOPE = NO +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +SKIP_FUNCTION_MACROS = YES +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DIR_GRAPH_MAX_DEPTH = 1 +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES \ No newline at end of file diff --git a/kernel/include/common/colour.h b/kernel/include/common/colour.h index f8a413b3..da870b55 100644 --- a/kernel/include/common/colour.h +++ b/kernel/include/common/colour.h @@ -12,7 +12,7 @@ namespace maxOS{ namespace common { - /*** + /** * @class Colour * @brief Stores the red, green, blue and alpha values of a colour */ diff --git a/kernel/include/common/outputStream.h b/kernel/include/common/outputStream.h index cd71e164..8cec82f3 100644 --- a/kernel/include/common/outputStream.h +++ b/kernel/include/common/outputStream.h @@ -14,7 +14,7 @@ namespace maxOS{ namespace common{ /** - * @class OutputStream + * @class GenericOutputStream * @brief A stream that can be written to. * * @tparam Type The type of the elements that will be written to the stream. diff --git a/kernel/include/common/rectangle.h b/kernel/include/common/rectangle.h index abee242e..97379585 100644 --- a/kernel/include/common/rectangle.h +++ b/kernel/include/common/rectangle.h @@ -11,7 +11,12 @@ namespace maxOS{ namespace common{ - // A rectangle template for use in the GUI system + /** + * @class Rectangle + * @brief Stores the left, top, width and height of a rectangle + * + * @tparam Type The type of the rectangle + */ template class Rectangle{ public: Type left { 0 }; diff --git a/kernel/include/common/time.h b/kernel/include/common/time.h index c53ad3fd..bc642a83 100644 --- a/kernel/include/common/time.h +++ b/kernel/include/common/time.h @@ -13,6 +13,7 @@ namespace maxOS{ /** * @struct Time + * @brief Stores the year, month, day, hour, minute and second of a time. */ struct Time{ diff --git a/kernel/include/drivers/clock/clock.h b/kernel/include/drivers/clock/clock.h index 7bf117c5..ab22f5bc 100644 --- a/kernel/include/drivers/clock/clock.h +++ b/kernel/include/drivers/clock/clock.h @@ -35,6 +35,7 @@ namespace maxOS { /** * @class ClockEventHandler + * @brief Handles the events triggered by the clock */ class ClockEventHandler : public common::EventHandler{ diff --git a/kernel/include/filesystem/fat32.h b/kernel/include/filesystem/fat32.h index 98f36581..16b46e38 100644 --- a/kernel/include/filesystem/fat32.h +++ b/kernel/include/filesystem/fat32.h @@ -16,6 +16,10 @@ namespace maxOS{ namespace filesystem{ + /** + * @struct BiosParameterBlock + * @brief Stores information about the FAT32 filesystem + */ struct BiosParameterBlock32{ uint8_t jump[3]; @@ -49,6 +53,10 @@ namespace maxOS{ } __attribute__((packed)); + /** + * @struct DirectoryEntry + * @brief Stores information about a file or directory + */ struct DirectoryEntry{ uint8_t name[8]; diff --git a/kernel/include/filesystem/msdospart.h b/kernel/include/filesystem/msdospart.h index 254384bc..b55beccd 100644 --- a/kernel/include/filesystem/msdospart.h +++ b/kernel/include/filesystem/msdospart.h @@ -14,6 +14,10 @@ namespace maxOS{ namespace filesystem{ + /** + * @struct PartitionTableEntry + * @brief Stores information about a partition + */ struct PartitionTableEntry{ uint8_t bootable; // 0x80 = bootable, 0x00 = not bootable @@ -33,6 +37,10 @@ namespace maxOS{ } __attribute__((packed)); + /** + * @struct MasterBootRecord + * @brief Stores information about the master boot record + */ struct MasterBootRecord{ uint8_t bootloader[440]; diff --git a/kernel/include/gui/font.h b/kernel/include/gui/font.h index 81c8a695..b50b3e43 100644 --- a/kernel/include/gui/font.h +++ b/kernel/include/gui/font.h @@ -43,7 +43,10 @@ namespace maxOS{ }; - + /** + * @class AmigaFont + * @brief A font that uses the Amiga 8x8 font + */ class AmigaFont : public Font{ public: AmigaFont(); diff --git a/kernel/include/gui/window.h b/kernel/include/gui/window.h index 66831660..b6e1082d 100644 --- a/kernel/include/gui/window.h +++ b/kernel/include/gui/window.h @@ -13,6 +13,10 @@ namespace maxOS{ namespace gui{ + /** + * @class Window + * @brief A window that can be moved and resized and contains a widget. + */ class Window : public CompositeWidget{ protected: diff --git a/kernel/include/hardwarecommunication/interrupts.h b/kernel/include/hardwarecommunication/interrupts.h index ffb02bc8..c8013d71 100644 --- a/kernel/include/hardwarecommunication/interrupts.h +++ b/kernel/include/hardwarecommunication/interrupts.h @@ -35,6 +35,27 @@ namespace maxOS { }; + /** + * @struct GateDescriptor + * @brief Describes a gate in the Interrupt Descriptor Table + */ + struct GateDescriptor { + uint16_t handler_address_low_bits; + uint16_t gdt_code_segment_selector; + uint8_t reserved; + uint8_t access; + uint16_t handler_address_high_bits; + } __attribute__((packed)); + + /** + * @struct InterruptDescriptorTablePointer + * @brief Describes the Interrupt Descriptor Table + */ + struct InterruptDescriptorTablePointer { + uint16_t size; + uint32_t base; + } __attribute__((packed)); + /** * @class InterruptManager * @brief Handles all interrupts and passes them to the correct handler @@ -50,21 +71,8 @@ namespace maxOS { InterruptHandler* m_interrupt_handlers[256]; //TODO: Make vector? system::ThreadManager* m_thread_manager; - struct GateDescriptor { - uint16_t handler_address_low_bits; - uint16_t gdt_code_segment_selector; - uint8_t reserved; - uint8_t access; - uint16_t handler_address_high_bits; - } __attribute__((packed)); - static GateDescriptor s_interrupt_descriptor_table[256]; - struct InterruptDescriptorTablePointer { - uint16_t size; - uint32_t base; - } __attribute__((packed)); - static void set_interrupt_descriptor_table_entry(uint8_t interrupt, uint16_t code_segment_selector_offset, void (*handler)(), uint8_t DescriptorPrivilegeLevel, uint8_t descriptor_type); static void InterruptIgnore(); diff --git a/kernel/include/memory/memoryIO.h b/kernel/include/memory/memoryIO.h index 9528f8cb..678809ed 100644 --- a/kernel/include/memory/memoryIO.h +++ b/kernel/include/memory/memoryIO.h @@ -36,7 +36,10 @@ namespace maxOS{ virtual uint8_t read(); }; - + /** + * @class MemIO16Bit + * @brief Handles 16 bit memory IO + */ class MemIO16Bit : public MemIO { public: MemIO16Bit(uint32_t address); @@ -46,6 +49,10 @@ namespace maxOS{ virtual uint16_t read(); }; + /** + * @class MemIO32Bit + * @brief Handles 32 bit memory IO + */ class MemIO32Bit : public MemIO { public: MemIO32Bit(uint32_t address); @@ -55,6 +62,10 @@ namespace maxOS{ virtual uint32_t read(); }; + /** + * @class MemIO64Bit + * @brief Handles 64 bit memory IO + */ class MemIO64Bit : public MemIO { public: MemIO64Bit(uint32_t address); diff --git a/kernel/include/memory/memorymanagement.h b/kernel/include/memory/memorymanagement.h index 1fc257e5..73734fee 100644 --- a/kernel/include/memory/memorymanagement.h +++ b/kernel/include/memory/memorymanagement.h @@ -12,6 +12,10 @@ namespace maxOS{ namespace memory{ + /** + * @struct MemoryChunk + * @brief Stores information about a memory chunk in the memory manager linked list + */ struct MemoryChunk{ MemoryChunk* next; diff --git a/kernel/include/system/multitasking.h b/kernel/include/system/multitasking.h index ad206223..9149ab46 100644 --- a/kernel/include/system/multitasking.h +++ b/kernel/include/system/multitasking.h @@ -13,6 +13,10 @@ namespace maxOS{ namespace system{ + /** + * @struct CPUState + * @brief Stores the state of the CPU registers + */ struct CPUState { //Pushed by kernel in interupt_stubs diff --git a/kernel/include/system/multithreading.h b/kernel/include/system/multithreading.h index 4b4102d9..df85f056 100644 --- a/kernel/include/system/multithreading.h +++ b/kernel/include/system/multithreading.h @@ -14,6 +14,10 @@ namespace maxOS{ namespace system{ + /** + * @class Thread + * @brief A execution thread that can be scheduled by the ThreadManager + */ class Thread { friend class ThreadManager; @@ -29,7 +33,10 @@ namespace maxOS{ void init(system::GlobalDescriptorTable *gdt, void entrypoint()); }; - + /** + * @class ThreadManager + * @brief Manages the scheduling of threads + */ class ThreadManager { private: diff --git a/kernel/include/system/process.h b/kernel/include/system/process.h index 9709a5ad..bd0ccd9f 100644 --- a/kernel/include/system/process.h +++ b/kernel/include/system/process.h @@ -13,6 +13,10 @@ namespace maxOS{ class Process; + /** + * @class Process + * @breif TODO + */ class Process{ // TODO: Re-work process class }; diff --git a/kernel/include/system/syscalls.h b/kernel/include/system/syscalls.h index a64cd00d..6b03eb99 100644 --- a/kernel/include/system/syscalls.h +++ b/kernel/include/system/syscalls.h @@ -11,6 +11,11 @@ namespace maxOS{ namespace system{ + + /** + * @class SyscallHandler + * @brief Handles system calls + */ class SyscallHandler : hardwarecommunication::InterruptHandler{ public: diff --git a/kernel/src/hardwarecommunication/interrupts.cpp b/kernel/src/hardwarecommunication/interrupts.cpp index af3c3442..36d329d4 100644 --- a/kernel/src/hardwarecommunication/interrupts.cpp +++ b/kernel/src/hardwarecommunication/interrupts.cpp @@ -13,7 +13,7 @@ using namespace maxOS::system; InterruptManager* InterruptManager::s_active_interrupt_manager = 0; OutputStream* InterruptManager::s_error_messages = 0; -InterruptManager::GateDescriptor InterruptManager::s_interrupt_descriptor_table[256]; +GateDescriptor InterruptManager::s_interrupt_descriptor_table[256]; ///__Handler__ diff --git a/toolchain/make_documentation.sh b/toolchain/make_documentation.sh new file mode 100755 index 00000000..e7e5c3f5 --- /dev/null +++ b/toolchain/make_documentation.sh @@ -0,0 +1,32 @@ +#!/bin/bash +source ./maxOS.sh + +# Go to the project root directory +cd ../docs/doxy + +# Install Required Packages +sudo apt-get install doxygen + +# Download required extensions +msg "Downloading extensions..." +ls doxygen-awesome.css || wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome.css +ls doxygen-awesome-darkmode-toggle.js || wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome-darkmode-toggle.js +ls doxygen-awesome-paragraph-link.js || wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome-paragraph-link.js +ls doxygen-awesome-interactive-toc.js || wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/main/doxygen-awesome-interactive-toc.js + +msg "Setting up extensions..." + +# Make a dummy header.html file +touch header.html + +# Create the header template +doxygen -w html header.html delete_me.html delete_me.css + +# Find head tag in script and add the extensions +sed -i '/<\/head>/i \n\n\n' header.html + +# Generate the documentation +msg "Generating documentation..." +doxygen Doxyfile + +msg "Documentation generated successfully!" \ No newline at end of file