hschumann2/TempleOS-Source-Code

1 2                              Directory Structure3 4/Home All your user data should be placed in here to ease backing-up your data.5When you install an application it will create a subdirectory of your /Home6directory for storage.7 8/Apps Applications are placed in subdirectories of /Apps.  Applications should9have a file called Install.HC.Z which will install the app, possibly making10files or directories in /Home.  The file, Load.HC.Z will load the application11into mem.  The file, Run.HC.Z, will usually load and execute the app.  To add an12app to your PersonalMenu, use <CTRL-l>, insert a macro with the PopUp option13checked and invoke the Run.HC.Z file.14 15/Demo Here you can find lots of sample code to do various things.16 17/Doc Here you can find documentation.18 19/Kernel The core of the operating system is found here.  Since priviledge levels20are not used, calling it a kernel is deceptive.  It is AOT compiled by21BootHDIns().  It is loaded by the boot loader and must fit in 640K.22 23/Compiler The compiler module src code is found here.  The compiler is AOT24compiled to produce a binary file which is loaded at boot.  It, too, is AOT25compiled by BootHDIns().26 27/Adam The non-kernel part of the operating system is found here.  It is JIT28compiled during boot.  The Adam Task is the father of all tasks, like Adam and29Eve.30 31/0000Boot Boot files go here.  Stage 2 of the TempleOS hard drive master boot32loader, the old hard drive master boot record which is just blk#0, and the33CD/DVD 0000Kernel.BIN.C file go here.  ASCII 0000 is near the top,34alphabetically, in case you use MagicISO.35 36 37 38                                 ::/Home Files39 40The home dir is specified with '~'.  The home dir is ::/Home unless you change41it with HomeSet() or compile the kernel with a cfg option.  An empty /Home dir42should be valid because it will get default files from the root dir.43 44~/PersonalMenu.DD a menu viewed with the <CTRL-m> key or by clicking "MENU" in45the upper left border area of a window.46 47~/PersonalNotes.DD a personal note file viewed with the <CTRL-SHIFT-M> key.48 49~/MakeHome.HC a file compiled by the Adam Task during StartOS.50 51~/Home* Copy Home* files from the root into ~ and customize them.  These files52are invoked when the Adam Task starts-up.53 54~/Once.HC a file invoked at the start-up of the first user.  Customize this!55 56~/Registry.HC can be edited by hand or deleted to reset to defaults.  Takes57affect next boot.58 59 60 61                              Application Policies62 63* Place applications in their own /Apps subdirectory.64 65* Make a file called Load.HC.Z to load the application.66 67* Make a file called Run.HC.Z to load and run the application, preferable by #in68cludeing the Load.HC.Z file.69 70* Place user data in a subdirectory of /Home, preferably naming the subdirectory71the same as the /Apps subdirectory.  Or, place data in the Registry.HC.Z file.72See ::/Demo/RegistryDemo.HC.73 74* If the app needs files in the /Home directory, make an /Apps file called Insta75ll.HC.Z or Install.IN.Z to create the /Home subdirectory.76 77 78 79                             Programming Guidelines80 81* Virtual mem/Paging is not used -- it is identity mapped in x86_64 mode.  The82stk does not grow, so alloc enough when the task (process) is Spawned and use83the heap for most things.  (The heap refers to MAlloc() and Free().)84 85* You can Free(NULL).86 87* See Naming Convention and Abbreviations.88 89* There are two modes of compiling, AOT Compile Mode and JIT Compile Mode.90Compilation is done in both -- neither is "interpreted".  Use JIT Mode.91 92* HolyC93 94* Use I64 instead of smaller int sizes because the compiler converts everything95to 64-bit.  Don't use unsigned unless it actually breaks.  A policy of signed96keeps it simple so you don't have to agonize over choices.97 98     U32 DistDist(U16 x1, U16 y1, U16 x2, U16 y2)99     {//This requires zero-extend when fetching args.100       return SqrI64(x1-x2)+SqrI64(y1-y2);101     }102 103     I64 DistDist(I64 x1, I64 y1, I64 x2, I64 y2)104     {105       return SqrI64(x1-x2)+SqrI64(y1-y2);106     }107 108* In-order, short circuit logic is assumed.109 110* Avoid boolean expression assignments.  Boolean assignments don't have short111circuit logic and are not compiled efficiently.  The Bool type is just an alias112for a 1 byte signed int -- nothing forces it to 1 or 0.  There is a ToBool()113function that will for to 1 ot 0, however.114 115* Glbl vars in AOT BIN modules are initialized to zero.  They occupy space in116BIN files.117 118* Bracketing code with PUSHFD CLI and POPFD will protect against simultaneous119accesses from tasks on one core.  To protect against multiple cores, you need a120locked semaphore.  I think semiphores need to be in their own cache line, but121I'm not sure.  I use lock bits in a lot of places not aligned.122 123* SysDbg() and IsSysDbg() are really handy when working on the compiler or124kernel.  It's just a bit you can set and test.125 126* I don't use U0 * because the size is zero for ptr arithmetic.127 128* Use CH_SHIFT_SPACE for spaces in quotes in source code because I run129Spaces-to-Tabs on source code.130 131* Do not use #if or #ifdef132 133 134 135                                Hash Sym Tables136 137* See ::/Adam/AHash.HC for examples of how the hash tables are set-up.138Basically, syms are placed into hash tables and child process hash tables are139chained to parents.  This provides scopes for vars and functions.140 141* adam_task->hash_table holds the HolyC syms loaded in on start-up.142 143* Fs->hash_table holds user HolyC syms and if a sym is not found, it checks144parents.  When a duplicate sym is added to the table, it overshadows the prev145sym.  When developing software, typically you include the file at the cmd146prompt, make changes and reinclude it.  Old syms are overshadowed but they are147still there.  Periodically, kill the TASK and start fresh when mem is low.  If148you wish your applications to free themselves instead of staying in mem, spawn149or PopUp() a task to run the application and kill it when it's done.150 151* To display the contents of a hash table, use the Who() routine or the152varients.  HashDepthRep() gives a histogram  of how long the chains are, in case153you wish to make hash table sizes bigger.154 155 156 157                               Assembly Language158 159See ::/Doc/Asm.DD.160 161* FS must always point to the cur CTask.162 163* GS must always point to the cur CCPU.164 165* Don't change the segment regs unless interrupts are off.  It's hard to do,166anyway.  SET_FS_BASE and SET_GS_BASE.167 168* When interacting with HolyC compiled code, preserve RBP, RSI, RDI, R10-R15169because the compiler uses these for reg vars.  You are free to clobber RAX, RBX,170RCX, RDX, R8 and R9.  See Compiler Reg Masks, PUSH_C_REGS and POP_C_REGS171 172* I recommend using the standard stk frame for functions because Caller() is173used to display the call stk, such as for the wallpaper.174        PUSH    RBP175        MOV     RBP,RSP176        SUB     RSP,nnnn177...178        LEAVE179        RET180 181* The args are removed from the stack with RET1 stmts.182 183        RET1    16      //remove two args184 185* No args are passed in regs.186 187* RAX holds function return values, of course.188 189* "MagicISO" is a trademark owned by MagicISO Corp.190