tristan/ZealOS
1
0
Fork 0
mirror of https://github.com/Zeal-Operating-System/ZealOS.git synced 2024-12-29 00:36:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
ZealOS/docs/Doc/GuideLines.DD.html
TomAwezome 1b75d91002 Fix Mount AHCI Port selection. 
Add arg to SATARep to specify drive types to show.
Add checks in AHCIPortInit to verify port signatures, add helper method to get signatures from port.
2021-08-02 16:40:05 -04:00

188 lines
21 KiB
HTML
Executable file
Raw Blame History

<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">
<meta name="generator" content="ZealOS V0.13">
<style type="text/css">
body {background-color:#fef1f0;}
.cF0{color:#000000;background-color:#fef1f0;}
.cF1{color:#0148a4;background-color:#fef1f0;}
.cF2{color:#3b7901;background-color:#fef1f0;}
.cF3{color:#057c7e;background-color:#fef1f0;}
.cF4{color:#bb2020;background-color:#fef1f0;}
.cF5{color:#9e42ae;background-color:#fef1f0;}
.cF6{color:#b57901;background-color:#fef1f0;}
.cF7{color:#b2b6af;background-color:#fef1f0;}
.cF8{color:#555753;background-color:#fef1f0;}
.cF9{color:#678fbb;background-color:#fef1f0;}
.cFA{color:#82bc49;background-color:#fef1f0;}
.cFB{color:#0097a2;background-color:#fef1f0;}
.cFC{color:#e26a6a;background-color:#fef1f0;}
.cFD{color:#c671bc;background-color:#fef1f0;}
.cFE{color:#c7ab00;background-color:#fef1f0;}
.cFF{color:#fef1f0;background-color:#fef1f0;}
</style>
</head>
<body>
<pre style="font-family:monospace;font-size:12pt">
<a name="l1"></a><span class=cF5> Directory Structure</span><span class=cF0>
<a name="l2"></a>
<a name="l3"></a></span><span class=cF2>/Home</span><span class=cF0> All your user data should be placed in here to ease backing-up your data. When you install an application it will
<a name="l4"></a>create a subdirectory of your </span><span class=cF2>/Home</span><span class=cF0> directory for storage.
<a name="l5"></a>
<a name="l6"></a></span><span class=cF2>/Apps</span><span class=cF0> Applications are placed in subdirectories of </span><span class=cF2>/Apps</span><span class=cF0>. Applications should have a file called </span><span class=cF2>Install.CC</span><span class=cF0> which will
<a name="l7"></a>install the app, possibly making files or directories in </span><span class=cF2>/Home</span><span class=cF0>. The file, </span><span class=cF2>Load.CC</span><span class=cF0> will load the application into mem. The
<a name="l8"></a>file, </span><span class=cF2>Run.CC</span><span class=cF0>, will usually load and execute the app. To add an app to your PersonalMenu, use </span><span class=cF2>&lt;CTRL-l&gt;</span><span class=cF0>, insert a macro with
<a name="l9"></a>the PopUp option checked and invoke the </span><span class=cF2>Run.CC</span><span class=cF0> file.
<a name="l10"></a>
<a name="l11"></a></span><span class=cF2>/Demo</span><span class=cF0> Here you can find lots of sample code to do various things.
<a name="l12"></a>
<a name="l13"></a></span><span class=cF2>/Doc</span><span class=cF0> Here you can find documentation.
<a name="l14"></a>
<a name="l15"></a></span><span class=cF2>/Kernel</span><span class=cF0> The core of the operating system is found here. Since priviledge levels are not used, calling it a </span><span class=cF2>kernel</span><span class=cF0> is
<a name="l16"></a>deceptive. It is </span><span class=cF2>AOT</span><span class=cF0> compiled by </span><a href="https://zeal-operating-system.github.io/ZealOS/System/Boot/BootHDIns.CC.html#l25"><span class=cF4>BootHDIns</span></a><span class=cF0>(). It is loaded by the boot loader and must fit in 640K.
<a name="l17"></a>
<a name="l18"></a></span><span class=cF2>/Compiler</span><span class=cF0> The compiler module src code is found here. The compiler is </span><span class=cF2>AOT</span><span class=cF0> compiled to produce a binary file which is loaded
<a name="l19"></a>at boot. It, too, is </span><span class=cF2>AOT</span><span class=cF0> compiled by </span><a href="https://zeal-operating-system.github.io/ZealOS/System/Boot/BootHDIns.CC.html#l25"><span class=cF4>BootHDIns</span></a><span class=cF0>().
<a name="l20"></a>
<a name="l21"></a></span><span class=cF2>/System</span><span class=cF0> The non-kernel part of the operating system is found here. It is </span><span class=cF2>JIT</span><span class=cF0> compiled during boot. The </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l154"><span class=cF4>System Task</span></a><span class=cF0> is the
<a name="l22"></a>most important task. It never dies.
<a name="l23"></a>
<a name="l24"></a></span><span class=cF2>/Boot</span><span class=cF0> Boot files go here. Stage 2 of the ZealOS hard drive master boot loader, the old hard drive master boot record which is
<a name="l25"></a>just blk#0, and the HDD &amp; CD/DVD </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/Kernel.PRJ.html#l1"><span class=cF4>Kernel.BIN.C</span></a><span class=cF0> file go here.
<a name="l26"></a>
<a name="l27"></a>
<a name="l28"></a>
<a name="l29"></a></span><span class=cF5> ::/Home Files</span><span class=cF0>
<a name="l30"></a>
<a name="l31"></a>The home dir is specified with </span><span class=cF2>'~'</span><span class=cF0>. The home dir is </span><span class=cF2>::/Home</span><span class=cF0> unless you change it with </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/BlkDev/DiskDirB.CC.html#l1"><span class=cF4>HomeSet</span></a><span class=cF0>() or compile the kernel with a
<a name="l32"></a>config option. An empty </span><span class=cF2>/Home</span><span class=cF0> dir should be valid because it will get default files from the root dir.
<a name="l33"></a></span><span class=cF4>
<a name="l34"></a></span><a href="https://zeal-operating-system.github.io/ZealOS/Home/PersonalMenu.DD.html#l1"><span class=cF4>~/PersonalMenu.DD</span></a><span class=cF0> a menu viewed with the </span><span class=cF2>&lt;CTRL-m&gt;</span><span class=cF0> key or by clicking &quot;</span><span class=cF2>MENU</span><span class=cF0>&quot; in the upper left border area of a window.
<a name="l35"></a></span><span class=cF4>
<a name="l36"></a></span><a href="https://zeal-operating-system.github.io/ZealOS/Home/PersonalNotes.DD.html#l1"><span class=cF4>~/PersonalNotes.DD</span></a><span class=cF0> a personal note file viewed with the </span><span class=cF2>&lt;CTRL-SHIFT-M&gt;</span><span class=cF0> key.
<a name="l37"></a></span><span class=cF4>
<a name="l38"></a></span><a href="https://zeal-operating-system.github.io/ZealOS/Home/MakeHome.CC.html#l1"><span class=cF4>~/MakeHome.CC</span></a><span class=cF0> a file compiled by the </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l154"><span class=cF4>System Task</span></a><span class=cF0> during </span><a href="https://zeal-operating-system.github.io/ZealOS/StartOS.CC.html#l41"><span class=cF4>StartOS</span></a><span class=cF0>.
<a name="l39"></a>
<a name="l40"></a></span><span class=cF4>~/Home*</span><span class=cF0> Copy </span><span class=cF2>Home*</span><span class=cF0> files from the root into </span><span class=cF2>~</span><span class=cF0> and customize them. These files are invoked when the </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l154"><span class=cF4>System Task</span></a><span class=cF0> starts-up.
<a name="l41"></a></span><span class=cF4>
<a name="l42"></a></span><a href="https://zeal-operating-system.github.io/ZealOS/Home/Once.CC.html#l1"><span class=cF4>~/Once.CC</span></a><span class=cF0> a file invoked at the start-up of the first user. Customize this!
<a name="l43"></a></span><span class=cF4>
<a name="l44"></a></span><a href="https://zeal-operating-system.github.io/ZealOS/Home/Registry.CC.html#l1"><span class=cF4>~/Registry.CC</span></a><span class=cF0> can be edited by hand or deleted to reset to defaults. Takes affect next boot.
<a name="l45"></a>
<a name="l46"></a>
<a name="l47"></a>
<a name="l48"></a></span><span class=cF5> Application Policies</span><span class=cF0>
<a name="l49"></a>
<a name="l50"></a>* Place applications in their own </span><span class=cF2>/Apps</span><span class=cF0> subdirectory.
<a name="l51"></a>
<a name="l52"></a>* Make a file called </span><span class=cF2>Load.CC</span><span class=cF0> to load the application.
<a name="l53"></a>
<a name="l54"></a>* Make a file called </span><span class=cF2>Run.CC</span><span class=cF0> to load and run the application, preferable by </span><span class=cF2>#include</span><span class=cF0>ing the </span><span class=cF2>Load.CC</span><span class=cF0> file.
<a name="l55"></a>
<a name="l56"></a>* Place user data in a subdirectory of </span><span class=cF2>/Home</span><span class=cF0>, preferably naming the subdirectory the same as the </span><span class=cF2>/Apps</span><span class=cF0> subdirectory. Or,
<a name="l57"></a>place data in the </span><span class=cF2>Registry.CC</span><span class=cF0> file. See </span><a href="https://zeal-operating-system.github.io/ZealOS/Demo/RegistryDemo.CC.html#l1"><span class=cF4>::/Demo/RegistryDemo.CC</span></a><span class=cF0>.
<a name="l58"></a>
<a name="l59"></a>* If the app needs files in the </span><span class=cF2>/Home</span><span class=cF0> directory, make an </span><span class=cF2>/Apps</span><span class=cF0> file called </span><span class=cF2>Install.CC</span><span class=cF0> or </span><span class=cF2>Install.IN</span><span class=cF0> to create the </span><span class=cF2>/Home</span><span class=cF0>
<a name="l60"></a>subdirectory.
<a name="l61"></a>
<a name="l62"></a>
<a name="l63"></a>
<a name="l64"></a></span><span class=cF5> Programming Guidelines</span><span class=cF0>
<a name="l65"></a>
<a name="l66"></a>* Virtual mem/Paging is not used -- it is identity mapped in </span><span class=cF2>x86_64</span><span class=cF0> mode. The stack does not grow, so alloc enough when the
<a name="l67"></a>task (process) is </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KTask.CC.html#l264"><span class=cF4>Spawn</span></a><span class=cF0>ed and use the heap for most things. (The </span><span class=cF2>heap</span><span class=cF0> refers to </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/Memory/MAllocFree.CC.html#l391"><span class=cF4>MAlloc</span></a><span class=cF0>() and </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/Memory/MAllocFree.CC.html#l387"><span class=cF4>Free</span></a><span class=cF0>().)
<a name="l68"></a>
<a name="l69"></a>* You can </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/Memory/MAllocFree.CC.html#l387"><span class=cF4>Free</span></a><span class=cF0>(</span><span class=cF2>NULL</span><span class=cF0>).
<a name="l70"></a>
<a name="l71"></a>* See </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l261"><span class=cF4>Naming Convention</span></a><span class=cF0> and </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l3"><span class=cF4>Abbreviations</span></a><span class=cF0>.
<a name="l72"></a>
<a name="l73"></a>* There are two modes of compiling, </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l179"><span class=cF4>AOT Compile Mode</span></a><span class=cF0> and </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l188"><span class=cF4>JIT Compile Mode</span></a><span class=cF0>. Compilation is done in both -- neither is
<a name="l74"></a>&quot;interpreted&quot;. Use </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Glossary.DD.html#l188"><span class=cF4>JIT Mode</span></a><span class=cF0>.
<a name="l75"></a>
<a name="l76"></a>* </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/CosmiC.DD.html#l1"><span class=cF4>CosmiC</span></a><span class=cF0>
<a name="l77"></a>
<a name="l78"></a>* Use </span><span class=cF2>I64</span><span class=cF0> instead of smaller int sizes because the compiler converts everything to 64-bit. Don't use unsigned unless it
<a name="l79"></a>actually breaks. A policy of signed keeps it simple so you don't have to agonize over choices.
<a name="l80"></a>
<a name="l81"></a> </span><span class=cF9>U32</span><span class=cF0> DistDist(</span><span class=cF9>U16</span><span class=cF0> x1, </span><span class=cF9>U16</span><span class=cF0> y1, </span><span class=cF9>U16</span><span class=cF0> x2, </span><span class=cF9>U16</span><span class=cF0> y2)
<a name="l82"></a> {</span><span class=cF2>//This requires zero-extend when fetching args.</span><span class=cF0>
<a name="l83"></a> </span><span class=cF1>return</span><span class=cF0> </span><span class=cF5>SqrI64</span><span class=cF0>(x1 - x2) + </span><span class=cF5>SqrI64</span><span class=cF0>(y1 - y2);
<a name="l84"></a> }
<a name="l85"></a>
<a name="l86"></a> </span><span class=cF9>I64</span><span class=cF0> DistDist(</span><span class=cF9>I64</span><span class=cF0> x1, </span><span class=cF9>I64</span><span class=cF0> y1, </span><span class=cF9>I64</span><span class=cF0> x2, </span><span class=cF9>I64</span><span class=cF0> y2)
<a name="l87"></a> {
<a name="l88"></a> </span><span class=cF1>return</span><span class=cF0> </span><span class=cF5>SqrI64</span><span class=cF0>(x1 - x2) + </span><span class=cF5>SqrI64</span><span class=cF0>(y1 - y2);
<a name="l89"></a> }
<a name="l90"></a>
<a name="l91"></a>* In-order, short circuit logic is assumed.
<a name="l92"></a>
<a name="l93"></a>* Avoid boolean expression assignments. Boolean assignments don't have short circuit logic and are not compiled efficiently.
<a name="l94"></a>The </span><span class=cF2>Bool</span><span class=cF0> type is just an alias for a 1 byte signed int -- nothing forces it to </span><span class=cF2>1</span><span class=cF0> or </span><span class=cF2>0</span><span class=cF0>. There is a </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelB.HH.html#l90"><span class=cF4>ToBool</span></a><span class=cF0>() function that will
<a name="l95"></a>for to </span><span class=cF2>1</span><span class=cF0> ot </span><span class=cF2>0</span><span class=cF0>, however.
<a name="l96"></a>
<a name="l97"></a>* Global vars in </span><span class=cF2>AOT</span><span class=cF0> BIN modules are initialized to zero. They occupy space in BIN files.
<a name="l98"></a>
<a name="l99"></a>* Bracketing code with </span><span class=cF2>PUSHFD CLI</span><span class=cF0> and </span><span class=cF2>POPFD</span><span class=cF0> will protect against simultaneous accesses from tasks on <u>one</u> core. To protect
<a name="l100"></a>against multiple cores, you need a locked semaphore. Semaphores might need to be in their own cache line. Lock bits are used
<a name="l101"></a>in a lot of places not aligned.
<a name="l102"></a>
<a name="l103"></a>* </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KMisc.CC.html#l247"><span class=cF4>SysDebug</span></a><span class=cF0>() and </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KMisc.CC.html#l252"><span class=cF4>IsSysDebug</span></a><span class=cF0>() are really handy when working on the compiler or kernel. It's just a bit you can set and test.
<a name="l104"></a>
<a name="l105"></a>* </span><span class=cF2>U0 *</span><span class=cF0> is not used because the size is zero for ptr arithmetic.
<a name="l106"></a>
<a name="l107"></a>* Do not use </span><span class=cF2>#if</span><span class=cF0> or </span><span class=cF2>#ifdef</span><span class=cF0>
<a name="l108"></a>
<a name="l109"></a>
<a name="l110"></a>
<a name="l111"></a></span><span class=cF5> Hash Sym Tables</span><span class=cF0>
<a name="l112"></a>
<a name="l113"></a>* See </span><a href="https://zeal-operating-system.github.io/ZealOS/System/Hash.CC.html#l1"><span class=cF4>::/System/Hash.CC</span></a><span class=cF0> for examples of how the hash tables are set-up. Basically, syms are placed into hash tables and child
<a name="l114"></a>process hash tables are chained to parents. This provides scopes for vars and functions.
<a name="l115"></a>
<a name="l116"></a>* </span><span class=cF2>sys_task-&gt;hash_table</span><span class=cF0> holds the </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/CosmiC.DD.html#l1"><span class=cF4>CosmiC</span></a><span class=cF0> syms loaded in on start-up.
<a name="l117"></a>
<a name="l118"></a>* </span><span class=cF2>Fs-&gt;hash_table</span><span class=cF0> holds user CosmiC syms and if a sym is not found, it checks parents. When a duplicate sym is added to the
<a name="l119"></a>table, it overshadows the prev sym. When developing software, typically you include the file at the cmd prompt, make changes
<a name="l120"></a>and reinclude it. Old syms are overshadowed but they are still there. Periodically, kill the TASK and start fresh when mem
<a name="l121"></a>is low. If you wish your applications to free themselves instead of staying in mem, spawn or </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/Job.CC.html#l447"><span class=cF4>PopUp</span></a><span class=cF0>() a task to run the
<a name="l122"></a>application and kill it when it's done.
<a name="l123"></a>
<a name="l124"></a>* To display the contents of a hash table, use the </span><a href="https://zeal-operating-system.github.io/ZealOS/System/Hash.CC.html#l169"><span class=cF4>Who</span></a><span class=cF0>() routine or the varients. </span><a href="https://zeal-operating-system.github.io/ZealOS/System/Hash.CC.html#l370"><span class=cF4>HashDepthRep</span></a><span class=cF0>() gives a histogram of how
<a name="l125"></a>long the chains are, in case you wish to make hash table sizes bigger.
<a name="l126"></a>
<a name="l127"></a>
<a name="l128"></a>
<a name="l129"></a></span><span class=cF5> Assembly Language</span><span class=cF0>
<a name="l130"></a>
<a name="l131"></a>See </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/Asm.DD.html#l1"><span class=cF4>::/Doc/Asm.DD</span></a><span class=cF0>.
<a name="l132"></a>
<a name="l133"></a>* </span><span class=cF2>FS</span><span class=cF0> must always point to the cur </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelA.HH.html#l3982"><span class=cF4>CTask</span></a><span class=cF0>.
<a name="l134"></a>
<a name="l135"></a>* </span><span class=cF2>GS</span><span class=cF0> must always point to the cur </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelA.HH.html#l4101"><span class=cF4>CCPU</span></a><span class=cF0>.
<a name="l136"></a>
<a name="l137"></a>* Don't change the segment regs unless interrupts are off. It's hard to do, anyway. </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KUtils.CC.html#l536"><span class=cF4>SET_FS_BASE</span></a><span class=cF0> and </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KUtils.CC.html#l522"><span class=cF4>SET_GS_BASE</span></a><span class=cF0>.
<a name="l138"></a>
<a name="l139"></a>* When interacting with </span><a href="https://zeal-operating-system.github.io/ZealOS/Doc/CosmiC.DD.html#l1"><span class=cF4>CosmiC</span></a><span class=cF0> compiled code, preserve </span><span class=cF2>RBP, RSI, RDI, R10-R15</span><span class=cF0> because the compiler uses these for reg vars. Yo
<a name="l140"></a>u are free to clobber </span><span class=cF2>RAX, RBX, RCX, RDX</span><span class=cF0>, </span><span class=cF2>R8</span><span class=cF0> and </span><span class=cF2>R9</span><span class=cF0>. See </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelA.HH.html#l1939"><span class=cF4>Compiler Reg Masks</span></a><span class=cF0>, </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelA.HH.html#l1911"><span class=cF4>PUSH_C_REGS</span></a><span class=cF0> and </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KernelA.HH.html#l1912"><span class=cF4>POP_C_REGS</span></a><span class=cF0>
<a name="l141"></a>
<a name="l142"></a>* It is recommended to use the standard stack frame for functions because </span><a href="https://zeal-operating-system.github.io/ZealOS/Kernel/KDebug.CC.html#l53"><span class=cF4>Caller</span></a><span class=cF0>() is used to display the call stack, such as
<a name="l143"></a>for the wallpaper.
<a name="l144"></a></span><span class=cF2> PUSH RBP
<a name="l145"></a> MOV RBP, RSP
<a name="l146"></a> SUB RSP, nnnn
<a name="l147"></a>...
<a name="l148"></a> LEAVE
<a name="l149"></a> RET
<a name="l150"></a></span><span class=cF0>
<a name="l151"></a>* The args are removed from the stack with </span><span class=cF2>RET1</span><span class=cF0> statements.
<a name="l152"></a>
<a name="l153"></a> </span><span class=cF2>RET1 16 //remove two args</span><span class=cF0>
<a name="l154"></a>
<a name="l155"></a>* No args are passed in regs.
<a name="l156"></a>
<a name="l157"></a>* RAX holds function return values, of course.
<a name="l158"></a></span><span class=cF8>
<a name="l159"></a>* &quot;MagicISO&quot; is a trademark owned by MagicISO Corp.
</span></pre></body>
</html>
Reference in a new issue View git blame Copy permalink