-
Notifications
You must be signed in to change notification settings - Fork 42
Files
There are a number of different C files in the master branch of Q OS at the moment. Although this is subject to change at any point due to refactoring or to enable easier development, it is currently not very well defined where different parts of code should be put. In this section we will discuss each file in the Q OS master branch and what should be written into it. We will only go over .c files because there respective .h versions are only to be used to define the functions and variables that are used within the .c counterpart. The .asm and .ld files should not be modified unless new files are added or a major part of the kernel is rewritten. An important note on assembly files, we use the Netwide Assembler (NASM) which accepts only Intel syntax as oppose to AT&T/Gas syntax. Also those have to be in the extension .asm otherwise prepare to rewrite the Makefile!
Okay... This is not a .c file. However this is like the classy <stdio.h>
. If you are looking for a function but do not want to take that extra time of searching and digging through (lazy), simply include this file.
Currently a very short and well defined file, assemblyFunctions.c is a file where functions should be written that require assembly-level access to the computer. The two functions currently written there, inportb
and outportb
are used to send and receive data from specified ports via __asm__
to run Assembly code within the C file. These two functions are currently used only to get the current position of the cursor within the Q OS terminal or writer app.
Although unlikely, if any functions you are writing require the usage of __asm__
then they should be written directly in assemblyFunctions.c and declared in assemblyFunctions.h.
This file is in charge of mapping keyboard to IRQ1. It is also the file where functions for read from console is. It should be pretty straight forward...
screenUtils.c is a good place to put functions that don't belong anywhere else when they don't need a whole new code file to store them in. Any functions to do with the screen, such as the already existing print(string, int)
and a non existing function that might exist someday, getLine(uint8)
, should be in screenUtils.c.
Where the definition of what should be in screenUtils.c becomes more ambiguous is what variables should be initiated there. Currently, all variables that are required in kernel.c or screenUtils.c are currently declared in screenUtils.h and initialized in screenUtils.c. This is a bad practice and we should create a new file such as kernelVariables.h that can be used to declare variables in Update 4 or above.
The file consoleUI.c should only contain functions that do with graphics (ha funny...). Even though the dev team current has not yet created real graphics, they have implemented a ncurses
like scheme. In fact as of v0.06+, the user interface has been changed to this new Look and Feel. The functions will be more colour or strict text placement oriented.
stringUtils.c is currently a pretty small file but is probably going to become a lot bigger soon because performing operations on strings is a really important part of programming in general and in Q OS we will need to have lots of functions that can be used to quickly perform string operations, which is the purpose of stringUtils.c.
Any code in stringUtils should be a function, and it should have something to do with modifying strings or performing calculations on them. There are currently only two functions in the file, streql(string, string)
and strlen(string)
. These have very simple purposes as they currently only are able to see if two strings have the same value and to check the length of a string respectively.
To summarize, f you are adding a new function to stringUtils.c, it should do something with strings - such as get the first x letters of a string and put the value into a second string. This file needs a lot of work currently to add functions that will let us get specific parts of a command entered in the Q Terminal, such as only letters between character 6 and character 10 and many other things.
This is obviously the most important file in the Q OS master branch currently because without it there would simply be no OS. Most code should be written here if it is not a function but instead it is using functions to do things at an OS level.
The only thing that should, under almost any circumstances, not be written in kernel.c, are functions. There are already four different files that are described in detail above that should be contain functions and kernel.c is specifically to use the functions that already exist and not create more.
If you have functions that don't belong in stringUtils.c because they don't actually modify strings and instead they actually change the byte values at the core of the CPU, this file is a good place to put your functions. Remember, as with all files in the /inc
folder of the Q OS Source Code to declare your functions and variables in the respective .h file which for byteUtils.c is obviously byteUtils.h.
To summarise, make sure that any functions written in byteUtils.c manipulate or move bytes, not strings. If they change strings and not bytes, they should be in stringUtils.c
This is a relatively complex file that should be used to contain functions that need to access the Interrupt Descriptor Tables (IDT). Functions in this file should be directly related to the BIOS-Based Interrupt system in Q OS.
Potentially a confusing file name, error.c isn't an error - it's actually a file for functions that deal with major errors. Currently only containing two functions, panic()
and panic_assert()
, this file should rarely need to be modified because it provides only core functions that don't need to be changed for processes that require them.
If you change functions or add new ones to error.c, your pull request may be less likely to be accepted when and if you make one unless the function changes in error.c are actually necessary for what you are trying to accomplish in your fork.
In the name of this file, fs stands for file system. That basically defines the purpose of this file - functions required for the Virtual File System implemented in Release 0.01 Alpha of Q OS that is still being finished. If you are changing code or creating something that requires read/write access to the file system, you probably don't need to modify this file. However, if what you are creating is adding new functionality to the file system, such as making it a FAT32 file system instead of a Virtual File System (something we are working on currently), then you would definitely need to change this file.
isr.c, or, interruptServiceRoutine.c, as this file would be called if it had an expanded name, is another important file for the Interrupt System on Q OS. Functions in this file typically have something to do with the Assembly language and therefore use functions from assemblyFunctions.c such as inportb
to manage the Interrupts in Q OS.
The need to modify this file is not very great currently as it provides all the functionality that it needs to at the moment, however if you are improving the Interrupt System on Q OS or modifying how it works, then changing this file is probably going to be necessary. Please comment code in this file especially well as the functions here can be very complex depending on what you are trying to do because they use Assembly Functions.
The name of this file might seem self explanatory, and it mostly is, however it is not a file where functions should be written, for example, to create a system wide clock that tells the user what the time is. This file is specifically for handling CPU Clock Updates and is currently based on JamesM's kernel development tutorials.