Bibliography and References

Advices & instructions

You can submit your questions on the student mailing list
(stos-student@lse.epita.fr), the language
of your question don’t matter (as long as it is in french or in english). If
you are shy, you can submit your questions directly by mail, or in person to
anyone of the lse members, they will redirect you if they don’t know. You can
also use irc to submit your questions (#lse on rezosup) but most of the time,
in order to have the question visible to everyone, we will redirect you to
the mailing lists.

We accept patches that improve the code and documentation of all the code
base. You need to submit them to the student mailing list
(stos-student@lse.epita.fr). You will
have bonus points for accepted patches and for correctly reviewed/tested
patches. Don’t hesitate to make suggestions and remarks on patches sent on
this mailing list.

All your patches must respect the Linux coding style. (see
Documentation/CodingStyle in you linux repository)

I will launch checkpatch on all your patches with the following command line:

You must not modify the headers in the include/kernel/ directory. THis is
the stos API, there is no need to change it. If you absolutely need a header,
you can put one in your module directory. But there is no reason to add
anything to a public header, most of the time, you will only leak
implementation details to the rest of the stos kernel

Look at all the code available in stos, especially the headers. There is a
lot of macros and inline functions that are already defined. You must use
them if it is appropriate. For example, there is macros that already wrap the
most used __attribute__ directives.

All your includes must be alphabetized.

In the stos kernel, we like to use arch specific include with the arch
directory instead of the directory with the name of the architecture. For
example you should not include kernel/i386/pm.h but kernel/arch/pm.h.
This have the nice side effect to put all the arch specific headers at the
top of the includes blocks. There is a link kernel/include/kernel/arch done
in the build directory to be able to use that.

Pay attention to your function names, they must give pertinent information of
what your function does.

For a lot of things, as you are writing code that is only code one time, you
don’t need to have a function, you can just add it (to your init module
function for example). If you add a function for code that is called only one
time, this is mostly for clarity and self-documentation.

When using bitfields in structure, avoid redefining size that are already
defined in a basic type. For example, prefer to have:

struct foo { u16 a; };

instead of:

struct foo { u32 a : 16; };

Your commit message must explain what your patch is doing, and waht it is
providing, as if it is a contribution for an open source project. You need to
explain what it does, and why. You can read as an example linux commit
messages. Also please avoid commit message like “add pm support in the stos
kernel”, we already know that a commit to stos is for stos.

Pay attention to your symbols visibility, if a symbol does not need to be
exported, it must be static. There is only 2 visibilities in C, static
and extern, the default visibility is extern, so, for a function these 2
declarations are the same:

extern void foo(void);
void foo(void);

Avoid unnecessary comments. This is useless to add a comment that explain
exactly what are you doing next. In general, comments should be avoided,
and if you really need one for your code to be clear, it is a sign that what
you wrote is not simple enough.

Mail review of your patches

All your code submission must pass by a mail review to be validated, this will
count as a bug part of your grade. Here is some advices and instructions for
that:

For all your patches, you must respect the Linux way
(Documentation/SubmittingPatches)

Don’t forget to sign you commits (“Signed-off-by” tag). You need to use your
real name for that, the mail address is at your convenience, but must
exists (-s option in git commit for example).

You must have a prefix “k1”, “k2”, “k3” in your mails, in order to see waht
step your are sending your mail for. For example, if this is the second
version of the second step, your prefix must be [PATCH k2 v2]. You can use
--subject-prefix with git format-patch to have them generated
automatically.

Please use a decent MUA (mail client) to send your mails, when in doubt,
using git send-email is probably the simplest way to have something
working.

Your patches will be considered accepted when you receive the Acked-by: tag
by mail. You need to report it in your mail/commits, in order to not lost it,
and for us to be able to see what has already been reviewed. These tags must
also be in your submition repositories.

Don’t send the next step if you haven’t got validation of the first one.

When you send a step, please send all the precedent step with it. We only
apply your patches to stos-student, so we need all your modification to be
able to apply your code.
So for example, if you are sending the step 2, you should have something like
this:
[PATCH k2 0/4] Submit step k2: Interrupt handling and Timers
[PATCH k2 1/4] i386: add memory protection module
[PATCH k2 2/4] i386: add interrupts module
[PATCH k2 3/4] i386: add irq handling with 8259a
[PATCH k2 4/4] i386: add timer module with i8254

If you have multiple patches, consider adding a cover letter (--cover
option for git format-patch)

When sending a new version, try to answer your patches or the discussion.

Use version tags to send new versions for your patches ([PATCH k1 v2] prefix
to your subject for example). You can use -vN to add them automatically.

having a recent version of git helps a lot.

git format-patch before using git send-email helps a lot, and --dry-run
option of git send-email too.

You really need to have a MUA (mail client) correclty configured to read/send
mails. This helps a lot to see your errors (no, gmail is not enough, it is
not able to follow threads correctly).

When we are making a comment about your code, you can discuss about it if you
don’t understand the meaning of the comment, just answer the mail with your
questions.

All remarks needs to be addressed.

If you have issues with git you can/should read gitworkflows(7) and
gittutorial(7), this can help a lot to understand.

Always try to reapply your commits after sending them to yourself. This helps
a lot.

Submission

For this project, you have to submit your work 2 times:

The test suite will run on the branch named “k1” of your personal repository.

For the second part, we will review your patches, moslty the form, coding style
and such. We will also give you advices on how to write better code.

Assignments

ksto-1: Memory Protection

For this first part, that serve as an introduction, you will implement a module
that handle the GDT for STOS.

You have to submit your code on the branch named “k1”. For the patches sent by
mail, you must have the prefix tag “k1”. (for example [PATCH k1])

module name : “pm”

compiled module filename : “pm.ko”

module directory : kernel/modules/arch/i386/pm

module type : M_MEMORY_INIT

module config variable : CONFIG_PM

You will need to implement set_gdt_gate() like its described inside
<kernel/arch/pm.h>. The init function should set the segments for standard
protected flat model with an high memory kernel, and a userland.

All the relevant segment selectors must also be set (don’t forget %es, %fs, and
%gs.)

Pay attention to pm.h header, all the segment described there must be
usable with your code. They don’t need to be set at init time, as you don’t
have all the informations yet, but other part of the code might need them.

ksto-2: Events

For this second part, you will have to implement 3 modules, in order to have an
functionnal event subsystem.