Differences between revisions 2 and 3
Revision 2 as of 2018-03-09 20:13:22
Size: 9178
Editor: eSyr
Comment: convert to moin markup
Revision 3 as of 2020-02-20 16:16:07
Size: 9385
Editor: eSyr
Comment: Updates for GSoC 2020
Deletions are marked like this. Additions are marked like this.
Line 46: Line 46:
Examples of system calls: `pciconfig_*`; `sys_debug_setcontext`, `swapcontext`, `rtas` on `power` (the latter two, however, are SPU-specific and it could be quite hard to verify their usage) . Generally, if a syscall has printargs as its decoder and there's no good reason for it (like, the syscall is deprecated, or printargs does good enough job for decoding its arguments), it's a possible candidate for a new decoder. The other possibility is some newly introduced system call (there were none during the 4.16 merge window, however). Examples of system calls: `pciconfig_*`; `sys_debug_setcontext`, `swapcontext`, `rtas` on `power` (the latter two, however, are SPU-specific and it could be quite hard to verify their usage) . Generally, if a syscall has printargs as its decoder and there's no good reason for it (like, the syscall is deprecated, or printargs does good enough job for decoding its arguments), it's a possible candidate for a new decoder. The other possibility is some newly introduced system calls (for example, in 5.6: `openat2`, `pidfd_getfd`) and/or system call sub-commands (`PR_[GS]ET_IO_FLUSHER` of the `prctl` syscall, new `IORING_REGISTER_*` commands of the `io_uring_register` syscall, new `BPF_MAP_*_BATCH` commands of the `bpf` syscall).
Line 48: Line 48:
Examples of ioctl commands: `GPIO_*`, `PERF_EVENT_IOC_*`, `LIRC_*`. Examples of ioctl commands: `GPIO_*`, `LIRC_*`, `USBDEVFS_*`.
Line 50: Line 50:
Example of netlink protocols: CAN, RDMA, L2TP. Example of netlink protocols: CAN, RDMA, L2TP, DEVLINK, ETHTOOL.

Introduction

It is strongly recommended that students who want to apply to the strace project for the GSoC submit a relatively small code-related patch to the strace project as part of their application. Think of these microprojects as the "Hello, world" of getting involved with the strace project; the coding aspect of the change can be relatively simple, but to make the change the student has to become familiar with many of the practical aspects of working on the strace project.

strace development is based on sending successive versions of patches or patch series to the mailing list until they are considered good and correct by the reviewers and Dmitry V. Levin, the strace maintainer, who will merge them. This process usually takes quite some time. By sending drafts of your microproject patches to the mailing list long before the deadline, you can show us that you are willing and able to work well using the strace development process.

It is *expected* that what you send will need several rounds of reviews and discussions. If you are not sure at all about a patch you can put [RFC/PATCH] at the beginning of its subject.

Consider a sample email thread which shows how a developer proposed a change and a patch series to implement it. The problem being solved, the design of the proposed solution, and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the discussion, to learn what is expected of you.

To complete a microproject, you will have to go through approximately the following steps:

  • Download and build the source code.
  • Read about the process for submitting patches.
  • Make the actual change. (Funnily, this is likely the only part is tought in college.)

  • Run the test suite and make sure it passes 100%.
  • Commit your change.
    • Make sure to write a good commit message that explains the reason for the change and any ramifications.
  • Optional, but recommended:

    • Create a fork of strace repository on github.com, sign in to Travis CI with your GitHub account, accepting the GitHub access permissions confirmation, and enable builds of your strace fork in your Travis CI profile (you only have to do these steps once). Afterwards you can push your changes to your fork and on https://travis-ci.org/your-github-name/strace/builds (example here) you can see if your changes pass the strace test suite on different configurations.

  • Submit your change to the strace-devel mailing list. For this step you probably want to use the commands git format-patch and git send-email.

    • Make sure that your email is formatted correctly: send a test version of the email to yourself and see if you can apply it to your repository using git am.

    • It is advisable to have core.whitespace and apply.whitespace git options being set to error-all.

    • It is also advised to check the patches with kernel's checkpatch.pl script.

  • Expect feedback, criticism, suggestions, etc. from the mailing list.
    • Note that not everyone puts sender in Cc: in replies, so it might be useful to subscribe to the mailing list first in order to timely get the replies.

  • Respond to it! and follow up with improved versions of your change. Even for a trivial patch you shouldn't be surprised if it takes two or more iterations before your patch is accepted.

    • This is the best part of participating in the strace community; it is your chance to get personalized instruction from very experienced peers!

The coding part of the microproject should be relatively small (say, up to one day). It's advisable to have your patch accepted into master by the time of your formal application, this way you can demonstrate that you have a basic level of competence, the ability to interact with the other strace developers, and can complete tasks.

When you submit your patch, please mention that you plan to apply for the GSoC. This will ensure that we take special care not to overlook your application among the large pile of others.

Students: Please attempt only ONE microproject. We want quality, not quantity! (Also, it takes work to collect the ideas, and it would be nice to have enough microprojects for everybody.) If you've already done a microproject and are itching to do more, then get involved in other ways, like writing new tests, finding and fixing other problems in the code, or improving the documentation or code comments, or helping to review other people's patches on the mailing list, or answering questions on the mailing list or in IRC, etc. In short, start doing things that other strace developers do!

Ideas for microprojects

The following are just ideas. Any small code-related change would be suitable. Just remember to keep the change small! It is much better for you to finish a small but complete change than to try something too ambitious and not get it done.

Most of the common syscalls usually parsed pretty well, but there's a big room for improvement regarding various ioctl command classes and arch-specific system calls.

A new parser, being new code, is expected to be supplied with relevant tests.

Examples of system calls: pciconfig_*; sys_debug_setcontext, swapcontext, rtas on power (the latter two, however, are SPU-specific and it could be quite hard to verify their usage) . Generally, if a syscall has printargs as its decoder and there's no good reason for it (like, the syscall is deprecated, or printargs does good enough job for decoding its arguments), it's a possible candidate for a new decoder. The other possibility is some newly introduced system calls (for example, in 5.6: openat2, pidfd_getfd) and/or system call sub-commands (PR_[GS]ET_IO_FLUSHER of the prctl syscall, new IORING_REGISTER_* commands of the io_uring_register syscall, new BPF_MAP_*_BATCH commands of the bpf syscall).

Examples of ioctl commands: GPIO_*, LIRC_*, USBDEVFS_*.

Example of netlink protocols: CAN, RDMA, L2TP, DEVLINK, ETHTOOL.

Add a test to the test suite

Add a test for a syscall that's not yet covered or not fully covered by the test suite. See https://codecov.io/github/strace/strace for a general idea what's covered and what's not, especially for files that have no or little code coverage (ioctl command parsers tend to be not covered, but they are not the only ones). As virtually every GSoC project expects writing some tests, the experience of extending test suite would be useful anyway.

Most of the tests in strace's test suite are currently generated; their generation is performed by tests/gen_tests.sh script from the information present in tests/gen_tests.in file. Please refer to strace's commit log for examples of new test implementations.

Extend -e trace=class syntax with new classes

strace currently supports desc, file, ipc, memory, network, process, pure, signal, and various stat- and statfs-related syscall classes. Additional classes might be useful, e.g. all open-like syscalls, all syscalls dealing with uid/gid, etc. Note that the newly added class is ought to be non-trivial, i.e. not easily covered with various specification features, such as -e trace=/ (regular expression specification). This was discussed in this list already, so please see the mailing list archive.

Try to fix some bugs

You can use list of bugs on GitHub and feature requests page as starting points.

How to find other ideas for microprojects

If you don't like for some reason the above microprojects or if you just want more choice, you may find other ideas for microprojects by searching the mailing list or the code base itself. In the code base you could search the code itself or the tests (in the "tests" directory).

When you find something you are interested to work on, please ask first on the mailing list if it's worth doing and if it's appropriate for a microproject before starting to work on what you find. Even if it looks straightforward, there could be hidden reasons why it is too difficult or just inappropriate.

MicroProjects (last edited 2022-03-08 17:53:11 by eSyr)