From 8148d0e0853e4d61de2c144eb9e62b3f892c8564 Mon Sep 17 00:00:00 2001 From: zdimension Date: Wed, 17 Jun 2015 11:15:29 +0200 Subject: [PATCH] Finished Directories.md and updated index.md --- Docs/Directories.md | 103 +++++++++++++++---------------- Docs/index.md | 147 +++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 189 insertions(+), 61 deletions(-) diff --git a/Docs/Directories.md b/Docs/Directories.md index 073171601..34e417106 100644 --- a/Docs/Directories.md +++ b/Docs/Directories.md @@ -1,80 +1,70 @@ - -### Topic is out of date! -***TODO: Must rewrite Directories for latest release*** ### Directories -At a first look, the directory structure of Cosmos is quite confusing. There -are folders with same names, two source folders and so on. I'll try to show -you how the directories are structured, so that you can find what you're -looking for +At a first look, the directory structure of Cosmos is quite confusing. There are folders with same names and so on. I'll try to show you how the directories are structured, so that you can find what you're looking for. + +#### \Artwork + +Just some Cosmos artwork. #### \Build -The build directory contains file used to build ISO images and Virtual -Machines files and images. There is a folder with support files for BOCHS, for -VirtualPc, for VMware, QEMU, for support for boot from ISO CD, USB, Ethernet -(PXE) +The build directory contains file used to build ISO images and Virtual Machines files and images. There is a folder with support files for BOCHS, for Virtual PC, for VMware, QEMU, for support for boot from ISO CD, USB, Ethernet (PXE) -There is also an additional folder **VSIP**. It normally contains a file -called _install.bat_. That file must be executed as you download the code and -everytime you change some code which is non-kernel related (eg. the debugger, -the VS integration package, the IL2CPU code etc) +#### \Demos -It compiles all the projects to libraries, creates a Win32 Installer and -setups the Visual Studio IP. At the end it starts Visual Studio. - -You should close Visual Studio before executing install.bat. +This folder contains some Cosmos demo projects to help you. #### \Docs -Just a bunch of bad-structured documentation about Cosmos +This folder contains the Cosmos documentation that you're currently reading. #### \QA -Todo. +This folder contains the old Cosmos build scripts. +It isn't used at the moment. #### \Resources -Here you can put any pdf, doc, rtf, txt which can be used as a reference help -to develop Cosmos. It also contains the folder **x86**. Inside you can find -many interesting references about the x86 architecture. +This folder contains the 3rd party libraries that Cosmos uses. #### \Setup -Contains scripts and languages to build the Cosmos User Kit Installer. The -creation (and execution) of the installer is started from -\Build\VSIP\install.bat +Contains scripts and languages to build the Cosmos User Kit Installer. The creation (and execution) of the installer is started from \install.bat. + #### \Source -Contains the code of the Cosmos project, including the Compiler, Installer, Debugger and the main features of Cosmos. It also contains unused code. +Contains all the code of the Cosmos project. You will spend most of your time here.including the Compiler, Installer, Debugger and the main features of Cosmos. It also contains unused code. -**TODO: Check the following:** Contains a lot of code which is now not used. It was used previously, but it was decided to take it away and to restructure the code organization. It may be reintegrated however in future, with some code changes. +It also contains the solution file of Cosmos and some support libraries. -It also contains the solution file of Cosmos and some support libraries, which -IMHO should be moved to Source2 +#### \Source\Cosmos.Assembler -#### \Source\Unused +This folder contains the Cosmos assembler, the thing that writes generated assembly code in the kernel file. -This folder contains work-in-progress or deprecated features, like FAT, VGA and Networking. - -#### \Source2 - -Contains the real code of Cosmos. You will spend most of your time here. -However as you open it, you get confused again. Another Build, another VSIP, -two or three Debug directories, etc. Let's summarize: - -#### \Source2\Build +#### \Source\Cosmos.Build.* Any code related to the building process of Cosmos with the exception of IL2CPU which is however executed from here. Contains code for executing ld, nasm, makeiso, MSBuild, and others. -#### \Source2\Compiler +#### \Source\Cosmos.Common -**TODO: Check**. This piece of code gives us the possibility to write Assembly in C#. In this way we can keep all in an OO-like style. +TODO + +#### \Source\Cosmos.Core.Plugs + +This folder contains plugs for + +#### \Source\Cosmos.Common + +TODO + +#### \Source2\XSharp.* + +This piece of code gives us the possibility to write Assembly in C#. In this way we can keep all in an OO-like style. #### \Source2\Debug @@ -82,11 +72,6 @@ Contains the Debug Engine and Connector code. Also gives the possibility to work with GDB. For more informations about debugging see [Debugger](debugger.htm) -#### \Demos - -Should contain examples of the use of the Cosmos User Kit. Actually only a -number Guess demo is available - #### \Source\IL2CPU Code for the IL2CPU program. It's the Cosmos AOT Compiler. Form more @@ -111,15 +96,14 @@ Contains most of the code of the kernel, including drivers and the core. TODO +#### \Source\Unused + +This folder contains work-in-progress or deprecated features, like FAT, VGA and Networking. + #### \Source2\UserKit TODO -#### \Users - -Custom code playground. You can put your examples, random code, and toughts -here - #### \Source2\Utils TODO @@ -129,3 +113,16 @@ TODO Contains the code for the integration with Visual Studio. Adds support for the Cosmos Kernel project tipe, and custom build steps. +#### \Source\.Tests + +If you see a folder with a name ending by Tests, it means it contains tests. + +#### \Source\.Plugs + +If you see a folder with a name ending by Plugs, it means it contains plugs for . + +#### \Users + +Custom code playground. You can put your examples, random code, and toughts +here + diff --git a/Docs/index.md b/Docs/index.md index 25ec60fb7..09524f7b8 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -1,15 +1,146 @@  -### Docs +### Introducing Cosmos -This is the main "working" docs area. Many of the docs may be out of date, but -we try to update them as we can. +Cosmos (C# Open Source Managed Operating System) is an operating system +development kit which uses Visual Studio as its development environment. +Despite C# in the name any .NET based language can be used including VB.NET, +Fortran, Delphi Prism, IronPython, F# and more. Cosmos itself and the kernel +routines are primarily written in C#, and thus the Cosmos name. Besides that, +NOSMOS (.NET Open Source Managed Operating System) sounds stupid. -### Navigation +Cosmos is not an operating system in the traditional sense, but instead it is +an "Operating System Kit", or as I like to say "Operating System Legos". +Cosmos lets you create operating systems just as Visual Studio and C# normally +let you create applications. Most users can write and boot their own operating +system in just a few minutes, all using Visual Studio. Since milestone 5, Cosmos includes an integrated project type in Visual Studio, and an +integrated debugger. You can debug your operating system directly from Visual +Studio using breakpoints. -The visual studio html editor is a bit sucky, espeically in later versions. So -the docs are not cross linked, instead simply browse the diretories for -topics. +Cosmos is available in two distributions, the developer kit (dev kit), and the +user kit. The dev kit is designed for users who want to work on Cosmos itself. +The user kit is designed for those who are interested in building their own +operating system and doing some Cosmos work. The dev kit might be thought of +as the Cosmos SDK. Most users should start off with the user kit as it is not +so overwhelming like the dev kit. This article focuses on the user kit. - _place_holder; +### Writing your first Operating System +Create a new project as you would any C# project, but select Cosmos as the +project type. + +![](http://i.imgur.com/mb5ZOEk.png) + +A starter project will be created. It looks very much like a standard C# +console application. + +![](http://i.imgur.com/zUJoj5Y.png) + +Program.cs contains the boot and execution code. Instead of seeing a Windows +console window, you will see the following: + +![](http://i.imgur.com/D3F9c4t.png) + +This is your operating system running in VMWare Player! Cosmos can of course +also be booted in VMWare Workstation, Hyper-V, Virtual PC, or on real +hardware. But by default Cosmos uses VMWare Player because it is both free, +and reliable. Cosmos can even debug in Visual Studio, even when running on +another machine. + +### Integrated Debugging + +Debugging is a major issue with operating system development. The Cosmos team +was not content enough to simply conquer building and deployment, we want to +make developing operating system as easy as developing Windows applications. +Debugging a Cosmos based operating system should feel very familiar to you. +Lets modify our project a little bit to show the effect, and set a breakpoint. + +![](http://i.imgur.com/Hf4LZ3c.png) + +Now run the project again. + +![](http://i.imgur.com/YLPmEUf.png) + +Note that the execution stopped at "Two"? That is becuase in Visual Studio our +project has stopped on a breakpoint. Simply press F5 to continue just as you +would in a normal application! + +In addition to breakpoints Cosmos also supports step into (F11) as well. Trace +over (F10) is not supported yet. + +### Debugger Communication + +The debugger uses the serial port to communicate. Because of this, debugging +only works wtih virtualization environments that support serial ports such as +VMWare. QEMU supports serial ports as well, but its serial port implementation +is seriously broken on Windows and makes debugging impossible using QEMU. To +debug on real hardware, you must use a physical serial cable. In the future +Cosmos will also support debugging over Ethernet. + +### Extra Debugging + +Cosmos supports some explicit methods that can be used to communicate with the +debugger and use additional functionality. It is accessed using the Debugger +class in the Cosmos.Debug namespace in the Cosmos.Kernel assembly. This +assembly is used by all Cosmos projects. + +### Code Based Breakpoints + + + Global.Dbg.Break(); + +Break can be used to issue a code based break. Visual Studio will break on the +line after this statement. + +![](http://i.imgur.com/Dupjm8y.png) + +Since Cosmos does not support conditional breakpoints in the IDE yet, code +base breaks are very useful for implementing such. For example: + +```csharp +if (x == 5) { + Global.Dbg.Break(); +} +``` + +Alternatively you can call the .NET class libary break: + + + System.Diagnostics.Debugger.Break(); + +Both functions will produce the same result. + +### Debug Output + +Debug strings can be output to the debug window of the host. Because Cosmos +does not support watches yet, this functionality can be very useful for +watching variable values and for performing tracing without breakpoints. + +```csharp +Global.Dbg.Send("Hello from Cosmos!"); +``` + +When this line is executed, it will send a message over the debugging channel +and it will appear in the Visual Studio output window. + +![](http://i.imgur.com/DHqwjiF.png) + +### What's the catch? + +There really is no catch. Everything I've shown here is functioning as seen. +No mockups were used. However we still have a lot of work to go. Items of +interest that are on our current task list include interfaces (necessary for +foreach), file systems (partial support exists), threads, networking, and +graphics. We have prototypes and experimentation for each, but none have been +rolled into the mainline Cosmos development as of yet. + +### What was that Syslinux thing I saw on boot? + +Cosmos does not run on Linux. A boot loader called Syslinux is used to boot +Cosmos. After booting, Syslinux is not used. Syslinux is a bootloader and is +not a Linux distro. + +### Obtaining Cosmos + + * [Source Code - Both dev kit and user kit](http://github.com/CosmosOS/Cosmos/) + * [Releases](https://github.com/CosmosOS/Cosmos/releases)