Skip to content
Snippets Groups Projects
Commit 5b9e8aba authored by Ştefan GHENESCU's avatar Ştefan GHENESCU
Browse files

Update file README.md

parent 371808cb
No related branches found
No related tags found
No related merge requests found
Pipeline #105964 passed
Stage: test
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 11 additions and 121 deletions
    README.md
    + 11
    − 121
    View file @ 5b9e8aba
    ......@@ -13,14 +13,14 @@ A firewall is a program that checks network packets against a series of filters
    **In a real setup**, the network card will receive real packets (e.g. packets having [`Ethernet`](https://en.wikipedia.org/wiki/Ethernet_frame), [`IP`](https://en.wikipedia.org/wiki/IPv4) headers plus payload) from the network and will send them to the firewall for processing.
    The firewall will decide if the packets are to be dropped or not and, if not, passes them further.
    **In this assignment**, instead of real network packets, we'll deal with made up packets consisting of a made up source (a number), a made up destination (also a number), a timestamp (also a number) and some payload.
    **In this project**, instead of real network packets, we'll deal with made up packets consisting of a made up source (a number), a made up destination (also a number), a timestamp (also a number) and some payload.
    And instead of the network card providing the packets, we'll have a **producer thread** creating these packets.
    The created packets will be inserted into a [`circular buffer`](https://en.wikipedia.org/wiki/Circular_buffer), out of which **consumer threads** (which implement the firewall logic) will take packets and process them in order to decide whether they advance to the destination.
    The result of this processing is a log file in which the firewall will record the decision taken (PASS or DROP) for each packet, along with other information such as timestamp.
    The purpose of this assignment is to:
    In this project I will:
    - implement the circular buffer, along with synchronization mechanisms for it to work in a multithreaded program
    ......@@ -28,18 +28,15 @@ The purpose of this assignment is to:
    - provide the log file containing the result of the packet processing
    ## Support Code
    ## Code
    The support code consists of the directories:
    The code consists of the directories:
    - `src/` contains the skeleton for the parallelized firewall and the already implemented serial code in `src/serial.c`.
    You will have to implement the missing parts marked as `TODO`
    - `src/` contains the code for the parallelized firewall and the serial code in `src/serial.c`.
    - `utils/` contains utility files used for debugging and logging.
    - `tests/` contains tests used to validate and grade the assignment.
    ## Implementation
    - `tests/` contains tests used to validate the project.
    ### Firewall Threads
    ......@@ -48,11 +45,9 @@ The packets will be added to a shared data structure (visible to all threads) by
    Each `consumer` thread picks a packet from the shared data structure, checks it against the filter function and writes the packet hash together with the drop/accept decision to a log file.
    `consumer` threads stop waiting for new packets from the `producer` thread and exit when the `producer` thread closes the connection to the shared data structure.
    The `consumer` threads **must not do any form of busy waiting**.
    When there are new packets that need to be handled, the `consumer` threads must be **notified**.
    **Waiting in a `while()` loop or sleeping is not considered a valid synchronization mechanism and points will be deducted.**
    The `consumer` threads **does not do any form of busy waiting**.
    When there are new packets that need to be handled, the `consumer` threads will be **notified**.
    Implement the `consumer` related functions marked with `TODO` in the `src/consumer.c` file.
    **The number of consumer threads will be passed as the 3rd command-line argument**
    ### Ring Buffers
    ......@@ -66,10 +61,7 @@ Thus, the shared ring buffer offers the following fields:
    - `cap` the size of the internal buffer.
    - `data` pointer to the internal buffer.
    Apart from these fields you have to add synchronization primitives in order to allow multiple threads to access the ring buffer in a deterministic manner.
    You can use mutexes, semaphores, conditional variables and other synchronization mechanisms offered by the `pthread` library.
    You will have to implement the following interface for the ring buffer:
    Apart from these fields I added synchronization primitives in order to allow multiple threads to access the ring buffer in a deterministic manner.
    - `ring_buffer_init()`: initialize the ring buffer (allocate memory and synchronization primitives).
    - `ring_buffer_enqueue()`: add elements to the ring buffer.
    ......@@ -89,11 +81,6 @@ We would like the logs to be sorted by the packet timestamp, the order that they
    Thus, the `consumers` should insert the packet information to the log file such as the result is ordered by timestamp.
    The printing format can be found in `./src/serial.c`
    The logs must be written to the file in ascending order during packet processing.
    **Sorting the log file after the consumer threads have finished processing is not considered a valid synchronization mechanism and points will be deducted.**
    ## Operations
    ### Building
    To build both the serial and the parallel versions, run `make` in the `src/` directory:
    ......@@ -106,102 +93,7 @@ student@so:~/.../assignments/parallel-firewall/src$ make
    That will create the `serial` and `firewall` binaries.
    ## Testing and Grading
    Testing is automated.
    Tests are located in the `tests/` directory.
    To test and grade your assignment solution, enter the `tests/` directory and run `grade.sh`.
    ```console
    student@so:~/.../content/assignments/parallel-firewall$ cd tests/
    ```
    ```console
    student@so:~/.../content/assignments/parallel-firewall/tests$ ./grade.sh
    ```
    Note that this requires linters being available.
    The easiest way to test the project is to use a Docker-based setup with everything installed and configured (see the [README.checker.md](README.checker.md) file for instructions).
    To create the tests, run:
    ```console
    student@so:~/.../content/assignments/parallel-firewall/tests$ make check
    ```
    To remove the tests, run:
    ```console
    student@so:~/.../content/assignments/parallel-firewall/tests$ make distclean
    ```
    When using `grade.sh` you will get a maximum of 90/100 points for general correctness and a maximum of 10/100 points for coding style.
    ### Restrictions
    - Threads must yield the cpu when waiting for empty/full buffers i.e. not doing `busy waiting`.
    - The logs must be written as they are processed and not after the processing is done, in ascending order by the timestamp.
    - The number of running threads must be at least `num_consumers + 1`, where `num_consumers` is the 3rd command-line argument of the `firewall` binary.
    ### Grades
    - 10 points are awarded for a single consumer solution that also implements the ring buffer
    - 50 points are awarded for a multi consumer solution
    - 30 points are awarded for a multi consumer solution that writes the logs in the sorted manner (bearing in mind the above restrictions)
    ### Running the Checker
    Each test is worth a number of points.
    The maximum grade is `90`.
    A successful run will show the output:
    ```console
    student@so:~/.../assignments/parallel-firewall/tests$ make check
    [...]
    Test [ 10 packets, sort False, 1 thread ] ...................... passed ... 3
    Test [ 1,000 packets, sort False, 1 thread ] ...................... passed ... 3
    Test [20,000 packets, sort False, 1 thread ] ...................... passed ... 4
    Test [ 10 packets, sort True , 2 threads] ...................... passed ... 5
    Test [ 10 packets, sort True , 4 threads] ...................... passed ... 5
    Test [ 100 packets, sort True , 2 threads] ...................... passed ... 5
    Test [ 100 packets, sort True , 4 threads] ...................... passed ... 5
    Test [ 1,000 packets, sort True , 2 threads] ...................... passed ... 5
    Test [ 1,000 packets, sort True , 4 threads] ...................... passed ... 5
    Test [10,000 packets, sort True , 2 threads] ...................... passed ... 5
    Test [10,000 packets, sort True , 4 threads] ...................... passed ... 5
    Test [20,000 packets, sort True , 2 threads] ...................... passed ... 5
    Test [20,000 packets, sort True , 4 threads] ...................... passed ... 5
    Test [ 1,000 packets, sort False, 4 threads] ...................... passed ... 5
    Test [ 1,000 packets, sort False, 8 threads] ...................... passed ... 5
    Test [10,000 packets, sort False, 4 threads] ...................... passed ... 5
    Test [10,000 packets, sort False, 8 threads] ...................... passed ... 5
    Test [20,000 packets, sort False, 4 threads] ...................... passed ... 5
    Test [20,000 packets, sort False, 8 threads] ...................... passed ... 5
    Checker: 90/100
    ```
    ### Running the Linters
    To run the linters, use the `make lint` command in the `tests/` directory:
    ```console
    student@so:~/.../assignments/parallel-firewall/tests$ make lint
    [...]
    cd .. && checkpatch.pl -f checker/*.sh tests/*.sh
    [...]
    cd .. && cpplint --recursive src/ tests/ checker/
    [...]
    cd .. && shellcheck checker/*.sh tests/*.sh
    ```
    Note that the linters have to be installed on your system: [`checkpatch.pl`](https://.com/torvalds/linux/blob/master/scripts/checkpatch.pl), [`cpplint`](https://github.com/cpplint/cpplint), [`shellcheck`](https://www.shellcheck.net/).
    They also need to have certain configuration options.
    It's easiest to run them in a Docker-based setup with everything configured.
    ### Fine-Grained Testing
    ### Testing
    Input tests cases are located in `tests/in/` and are generated by the checker.
    The expected results are generated by the checker while running the serial implementation.
    ......@@ -209,6 +101,4 @@ If you want to run a single test, use the below commands while in the `src/` dir
    ```console
    student@so:~/.../assignments/parallel-firewall/src$ ./firewall ../tests/in/test_<num_packets>.in <output_file> <number_of_consumers>
    ```
    Results provided by the serial and parallel implementation must be the same for the test to successfully pass.
    ```
    \ No newline at end of file
    0% or .
    You are about to add 0 people to the discussion. Proceed with caution.
    Finish editing this message first!
    Please register or to comment