Materials for STOS

Course

Slides:

  • base repository: git://git.lse.epita.fr/stos-student.git

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:

    checkpatch.pl –no-tree –strict –show-types –ignore=FILE_PATH_CHANGES,BIT_MACRO

  • 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.
  • You have also to submit a patchset of your work, by mail at stos-1@lse.epita.fr

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.

You have to submit your code on the branch named “k2”.

IDT
  • module name: “interrupts”
  • compiled module filename: “interrupts.ko”
  • module directory: kernel/modules/arch/i386/interrupts
  • module type: M_INTERRUPTS
  • module config variable: CONFIG_INTERRUPTS
  • module dependancies: M_MEMORY_INIT

For this first module, you will need to implement 2 functions:

  • interrupt_add_isr()
  • interrupt_rm_isr()
PIC
  • module name: “8259A”
  • compiled module filename: “8259A.ko”
  • module directory: kernel/modules/arch/i386/8259A
  • module type: M_IRQ
  • module config variable: CONFIG_8259A
  • module dependancies: M_INTERRUPTS | M_KMALLOC

For this first module, you will need to implement 6 functions:

  • unmask_irq()
  • mask_irq()
  • mask_all_irq()
  • add_irq_handler()
  • rm_irq_handler()
  • acknowledge_irq()

When you declare your irq handlers, the right type to use is:

struct irq_handler {
	/* needed fields for you irq */
	struct list_node next;
};

static struct list_node handlers[16];
PIT
  • module name: “i8254”
  • compiled module filename: “i8254.ko”
  • module directory: kernel/modules/arch/i386/i8254
  • module type: M_TIMER
  • module config variable: CONFIG_I8254
  • module dependancies: M_IRQ

For this module, you will need to implement 1 function:

  • set_periodic_timer()

ksto-3: Pagination

For this second part, you will have to implement 1 module, in order to have a working paging system.

You have to submit your code on the branch named “k3”.

Pagination
  • module name: “pagination”
  • compiled module filename: “pagination.ko”
  • module directory: kernel/modules/arch/i386/pagination
  • module type: M_PAGINATION | M_PAGE_ALLOCATOR
  • module config variable: CONFIG_PAGINATION
  • module dependancies: M_INTERRUPTS | M_FRAME_ALLOCATOR

For this module, you will need to implement 5 functions:

  • alloc_pages()
  • map_pages()
  • map_io()
  • unmap_pages()
  • unmap_io()

ksto-4: Scheduling

In this last part, you will have to implement the scheduling inside the stos kernel. After this one, you should have a working OS, with the userland enabled.

You have to submit your code on the branch named “k3”.

Scheduling
  • module name: “scheduler”
  • compiled module filename: “scheduler.ko”
  • module directory: kernel/modules/scheduler
  • module type: M_SCHED
  • module config variable: CONFIG_SCHEDULER
  • module dependancies: M_TASK | M_TIMER

For this module, you will need to implement 4 functions:

  • __sleep_on()
  • enqueue_task()
  • schedule()
  • start_scheduling()
  • wake_up()
  • wake_up_task()