Skip to content

Commit f1be7e5

Browse files
razvandrazvand
committed
Documentation: teaching: Add page for SO2 Transport Protocol assignment
Signed-off-by: Razvan Deaconescu <razvan.deaconescu@cs.pub.ro>
1 parent ac83b91 commit f1be7e5

File tree

2 files changed

+253
-0
lines changed

2 files changed

+253
-0
lines changed

‎Documentation/teaching/so2/assign4-transport-protocol.rst

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
=====================================
2+
Assignment 4 - SO2 Transport Protocol
3+
=====================================
4+
5+
- Deadline: :command:`Monday, May, 31, 2021, 23:00`
6+
- This assignment can be made in teams (max 2). Only one of them must submit the assignment, and the names of the student should be listed in a README file.
7+
8+
Implement a simple datagram transport protocol - STP (*SO2 Transport Protocol*).
9+
10+
Assignment's Objectives
11+
=======================
12+
13+
* gaining knowledge about the operation of the networking subsystem in the Linux kernel
14+
* obtaining skills to work with the basic structures of the networking subsystem in Linux
15+
* deepening the notions related to communication and networking protocols by implementing a protocol in an existing protocol stack
16+
17+
Statement
18+
=========
19+
20+
Implement, in the Linux kernel, a protocol called STP (*SO2 Transport Protocol*), at network and transport level, that works using datagrams (it is not connection-oriented and does not use flow-control elements).
21+
22+
The STP protocol acts as a Transport layer protocol (port-based multiplexing) but operates at level 3 (Network) of `the OSI stack <http://en.wikipedia.org/wiki/OSI_model>`__, above the Data Link level.
23+
24+
The STP header is defined by the ``struct stp_header`` structure:
25+
26+
.. code-block:: c
27+
28+
struct stp_header {
29+
__be16 dst;
30+
__be16 src;
31+
__be16 len;
32+
__u8 flags;
33+
__u8 csum;
34+
};
35+
36+
37+
where:
38+
39+
* ``len`` is the length of the packet in bytes (including the header);
40+
* ``dst`` and ``src`` are the destination and source ports, respectively;
41+
* ``flags`` contains various flags, currently unused (marked *reserved*);
42+
* ``csum`` is the checksum of the entire package including the header; the checksum is calculated by exclusive OR (XOR) between all bytes.
43+
44+
Sockets using this protocol will use the ``AF_STP`` family.
45+
46+
The protocol must work directly over Ethernet. The ports used are between ``1`` and ``65535``. Port ``0`` is not used.
47+
48+
The definition of STP-related structures and macros can be found in the `assignment support header <https://github.com/linux-kernel-labs/linux/blob/master/tools/labs/templates/assignments/4-stp/stp.h>`__.
49+
50+
Implementation Details
51+
======================
52+
53+
The kernel module will be named **af_stp.ko**.
54+
55+
You have to define a structure of type `net_proto_family <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/net.h#L200>`__, which provides the operation to create STP sockets.
56+
Newly created sockets are not associated with any port or interface and cannot receive / send packets.
57+
You must initialize the `socket ops field <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/net.h#L124>`__ with the list of operations specific to the STP family.
58+
This field refers to a structure `proto_ops <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/net.h#L136>`__ which must include the following functions:
59+
60+
* ``release``: releases an STP socket
61+
* ``bind``: associates a socket with a port (possibly also an interface) on which packets will be received / sent:
62+
63+
* there may be bind sockets only on one port (not on an interface)
64+
* sockets associated with only one port will be able to receive packets sent to that port on all interfaces (analogous to UDP sockets associated with only one port); these sockets cannot send packets because the interface from which they can be sent via the standard sockets API cannot be specified
65+
* two sockets cannot be binded to the same port-interface combination:
66+
67+
* if there is a socket already binded with a port and an interface then a second socket cannot be binded to the same port and the same interface or without a specified interface
68+
* if there is a socket already binded to a port but without a specified interface then a second socket cannot be binded to the same port (with or without a specified interface)
69+
70+
* we recommend using a hash table for bind instead of other data structures (list, array); in the kernel there is a hash table implementation in the `hashtable.h header <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/hashtable.h>`__
71+
72+
* ``connect``: associates a socket with a remote port and hardware address (MAC address) to which packets will be sent / received:
73+
74+
* this should allow ``send`` / ``recv`` operations on the socket instead of ``sendmsg`` / ``recvmsg`` or ``sendto`` / ``recvfrom``
75+
* once connected to a host, sockets will only accept packets from that host
76+
* once connected, the sockets can no longer be disconnected
77+
78+
* ``sendmsg``, ``recvmsg``: send or receive a datagram on an STP socket:
79+
80+
* for the *receive* part, metainformation about the host that sent the packet can be stored in the `cb field in sk_buff <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/skbuff.h#L650>`__
81+
82+
* ``poll``: the default function ``datagram_poll`` will have to be used
83+
* for the rest of the operations the predefined stubs in the kernel will have to be used (``sock_no_*``)
84+
85+
.. code-block:: c
86+
87+
static const struct proto_ops stp_ops = {
88+
.family = PF_STP,
89+
.owner = THIS_MODULE,
90+
.release = stp_release,
91+
.bind = stp_bind,
92+
.connect = stp_connect,
93+
.socketpair = sock_no_socketpair,
94+
.accept = sock_no_accept,
95+
.getname = sock_no_getname,
96+
.poll = datagram_poll,
97+
.ioctl = sock_no_ioctl,
98+
.listen = sock_no_listen,
99+
.shutdown = sock_no_shutdown,
100+
.setsockopt = sock_no_setsockopt,
101+
.getsockopt = sock_no_getsockopt,
102+
.sendmsg = stp_sendmsg,
103+
.recvmsg = stp_recvmsg,
104+
.mmap = sock_no_mmap,
105+
.sendpage = sock_no_sendpage,
106+
};
107+
108+
Socket operations use a type of address called ``sockaddr_stp``, a type defined in the `assignment support header <https://github.com/linux-kernel-labs/linux/blob/master/tools/labs/templates/assignments/4-stp/stp.h>`__.
109+
For the *bind* operation, only the port and the index of the interface on which the socket is bind will be considered.
110+
For the *receive* operation, only the ``addr`` and ``port`` fields in the structure will be filled in with the MAC address of the host that sent the packet and with the port from which it was sent.
111+
Also, when sending a packet, the destination host will be obtained from the ``addr`` and ``port`` fields of this structure.
112+
113+
You need to register a structure `packet_type <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/netdevice.h#L2222>`__, using the call `dev_add_pack <http://elixir.free-electrons.com/linux/v4.9.11/source/net/core/dev.c#L386>`__ to be able to receive STP packets from the network layer.
114+
115+
The protocol will need to provide an interface through the *procfs* file system for statistics on sent / received packets.
116+
The file must be named ``/proc/net/stp_stats``, specified by the ``STP_PROC_FULL_FILENAME`` macro in `assignment support header <https://github.com/linux-kernel-labs/linux/blob/master/tools/labs/templates/assignments/4-stp/stp.h>`__.
117+
The format must be of simple table type with ``2`` rows: on the first row the header of the table, and on the second row the statistics corresponding to the columns.
118+
The columns of the table must be in order:
119+
120+
.. code::
121+
122+
RxPkts HdrErr CsumErr NoSock NoBuffs TxPkts
123+
124+
where:
125+
126+
* ``RxPkts`` - the number of packets received
127+
* ``HdrErr`` - the number of packets received with header errors (packets too short or with source or destination 0 ports)
128+
* ``CsumErr`` - the number of packets received with checksum errors
129+
* ``NoSock`` - the number of received packets for which no destination socket was found
130+
* ``NoBuffs`` - the number of received packets that could not be received because the socket queue was full
131+
* ``TxPkts`` - the number of packets sent
132+
133+
To create or delete the entry specified by ``STP_PROC_FULL_FILENAME`` we recommend using the functions `proc_create <http://elixir.free-electrons.com/linux/v4.9.11/source/include/linux/proc_fs.h#L30>`__ and `proc_remove <http://elixir.free-electrons.com/linux/v4.9.11/source/fs/proc/generic.c#L636>`__.
134+
135+
Sample Protocol Implementations
136+
-------------------------------
137+
138+
For examples of protocol implementation, we recommend the implementation of `PF_PACKET <http://elixir.free-electrons.com/linux/v4.9.11/source/net/packet/af_packet.c>`__ sockets and the various functions in `UDP implementation <http: //elixir.free-electrons.com/linux/v4.9.11/source/net/ipv4/udp.c>`__ or `IP implementation <http://elixir.free-electrons.com/linux/v4.9.11/source/net/ipv4/af_inet.c>`__.
139+
140+
Testing
141+
=======
142+
143+
In order to simplify the assignment evaluation process, but also to reduce the mistakes of the submitted assignments, the assignment evaluation will be done automatically with with the help of public tests that are in the new infrastructure.
144+
For local testing, use the following commands:
145+
146+
.. code-block:: console
147+
148+
$ git clone https://github.com/linux-kernel-labs/linux.git
149+
$ cd linux/tools/labs
150+
$ LABS=assignments/4-stp make skels
151+
$ #the development of the assignment will be written in the 4-stp directory
152+
$ make build
153+
$ make copy
154+
$ make boot
155+
156+
tcpdump
157+
-------
158+
159+
You can use the ``tcpdump`` utility to troubleshoot sent packets.
160+
The tests use the loopback interface; to track sent packets you can use a command line of the form:
161+
162+
.. code:: console
163+
164+
tcpdump -i lo -XX
165+
166+
You can use a static version of `tcpdump <http://elf.cs.pub.ro/so2/res/teme/tcpdump>`__.
167+
To add to the ``PATH`` environment variable in the virtual machine, copy this file to ``qemu-so2/fsimg/bin``.
168+
Create the directory if it does not exist. Remember to give the ``tcpdump`` file execution permissions:
169+
170+
.. code:: console
171+
172+
# In the qemu-so2 directory
173+
mkdir fsimg / bin
174+
wget http://elf.cs.pub.ro/so2/res/teme/tcpdump -O fsimg / bin / tcpdump
175+
chmod 755 fsimg / bin / tcpdump
176+
177+
Tips
178+
----
179+
180+
To increase your chances of getting the highest grade, read and follow the Linux kernel coding style described in the `Coding Style document <https://elixir.bootlin.com/linux/v4.19.19/source/Documentation/process/coding-style.rst>`__.
181+
182+
Also, use the following static analysis tools to verify the code:
183+
184+
* checkpatch.pl
185+
186+
.. code-block:: console
187+
188+
$ linux/scripts/checkpatch.pl --no-tree --terse -f /path/to/your/file.c
189+
190+
* sparse
191+
192+
.. code-block:: console
193+
194+
$ sudo apt-get install sparse
195+
$ cd linux
196+
$ make C=2 /path/to/your/file.c
197+
198+
* cppcheck
199+
200+
.. code-block:: console
201+
202+
$ sudo apt-get install cppcheck
203+
$ cppcheck /path/to/your/file.c
204+
205+
Penalties
206+
---------
207+
208+
Information about assigments penalties can be found on the `General Directions page <https://ocw.cs.pub.ro/courses/so2/teme/general>`__.
209+
210+
In exceptional cases (the assigment passes the tests by not complying with the requirements) and if the assigment does not pass all the tests, the grade will may decrease more than mentioned above.
211+
212+
Submitting the assigment
213+
------------------------
214+
215+
The assignment archive will be submitted to vmchecker, according to the rules on the `rules page <https://ocw.cs.pub.ro/courses/so2/reguli-notare#reguli_de_trimitere_a_temelor>`__.
216+
217+
From the vmchecker interface choose the `Transport Protocol` option for this assigment.
218+
219+
Resources
220+
=========
221+
222+
* `Lecture 10 - Networking <https://linux-kernel-labs.github.io/refs/heads/master/so2/lec10-networking.html>`__
223+
* `Lab 10 - Networking <https://linux-kernel-labs.github.io/refs/heads/master/so2/lab10-networking.html>`__
224+
* Linux kernel sources
225+
226+
* `Implementing PF_PACKET sockets <http://elixir.free-electrons.com/linux/v4.9.11/source/net/packet/af_packet.c>`__
227+
* `Implementation of the UDP protocol <http://elixir.free-electrons.com/linux/v4.9.11/source/net/ipv4/udp.c>`__
228+
* `Implementation of the IP protocol <http://elixir.free-electrons.com/linux/v4.9.11/source/net/ipv4/af_inet.c>`__
229+
230+
* Understanding Linux Network Internals
231+
232+
* chapters 8-13
233+
234+
* `assignment support header <https://github.com/linux-kernel-labs/linux/blob/master/tools/labs/templates/assignments/4-stp/stp.h>`__
235+
236+
We recommend that you use GitLab to store your homework. Follow the directions in `README <https://github.com/systems-cs-pub-ro/so2-assignments/blob/master/README.md>`__ and on the dedicated `git wiki page <https://ocw.cs.pub.ro/courses/so2/teme/folosire-gitlab>`__.
237+
238+
The resources for the assignment can also be found in the `so2-assignments <https://github.com/systems-cs-pub-ro/so2-assignments>`__ repo on GitHub.
239+
The repo contains a `Bash script <https://github.com/systems-cs-pub-ro/so2-assignments/blob/master/so2-create-repo.sh>`__ that helps you create a private repository on the faculty `GitLab <https://gitlab.cs.pub.ro/users/sign_in>`__ instance.
240+
Follow the tips from the `README <https://github.com/systems-cs-pub-ro/so2-assignments/blob/master/README.md>`__ and on the dedicated `Wiki page <https://ocw.cs.pub.ro/courses/so2/teme/folosire-gitlab>`__.
241+
242+
Questions
243+
=========
244+
245+
For questions about the assigment, you can consult the mailing `list archives <http://cursuri.cs.pub.ro/pipermail/so2/>`__ or send an e-mail (you must be `registered <http://cursuri.cs.pub.ro/cgi-bin/mailman/listinfo/so2>`__).
246+
Please follow and follow `the tips for use of the list <https://ocw.cs.pub.ro/courses/so2/resurse/lista-discutii#mailing-list-guidelines>`__.
247+
248+
Before you ask a question, make sure that:
249+
250+
* you have read the statement of the assigment well
251+
* the question is not already presented on the `FAQ page <https://ocw.cs.pub.ro/courses/so2/teme/tema2/faq>`__
252+
* the answer cannot be found in the `mailing list archives <http://cursuri.cs.pub.ro/pipermail/so2/>`__

‎Documentation/teaching/so2/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,4 @@ Operating Systems 2
4646
assign2-driver-uart.rst
4747
assign3-software-raid.rst
4848
assign-chall-pitix.rst
49+
assign4-transport-protocol.rst

0 commit comments

Comments
 (0)