Project name
Student: TylerBaxter
Mentor: WarnerLosh (imp@FreeBSD.org), KyleEvans (kevans@FreeBSD.org)
Project description
The current FreeBSD system call creation script, sys/tools/makesyscalls.lua, was implemented by Kyle Evans and iterated on by Brooks Davis. Its purpose is to streamline the introduction of system calls into the FreeBSD kernel. makesyscalls.lua is a transliteration of FreeBSD’s original makesyscalls.awk script from awk to Lua. It’s a monolithic script that has kept much of the procedural-oriented awk code. It does not take full advantage of modern features of Lua (object-oriented design) and has been difficult to add additional features to.
FreeBSD system call creation will be further improved by a complete refactor of makesyscalls.lua to have easily extensible objects and dynamically-called modules. The goal is to strip the monolithic script into an easily extendable interface. It will utilize classes to give extensible methods to objects, mainly utilizing the facade and command design patterns, to give a more "bite-sized" interface to the previously procedural code. Lua modules will provide better namespacing of globals, dynamic generation of output files, and more modules with different tasks may be easily added. After refactoring, the previous functionality of the original script can be achieved simply by calling the necessary modules. By taking advantage of modern Lua features and object-oriented design makesyscalls.lua can be easily extended, called dynamically, or serve as the basis for future scripts.
The benefit to FreeBSD is further streamlining in the creation of system calls, a more maintainable interface, and a strong foundation to build upon in the development of future system call creation tools. There is a clear intent to expand on the work of Kyle Evans and Brooks Davis, and my refactor will address that intent and provide an extensible interface to do so. It will further demystify the process of system call creation and allow others to more easily contribute. Warner Losh has done preliminary work on refactoring makesyscalls.lua, which will serve as the basis for my refactor. It is unfinished and does not incorporate Brooks Davis' recent commits. A successful project will be finishing the pre-established work, incorporating recent commits, and the previously stated design outcomes.
There is still much work to be done and critical design choices to be made (e.g., is it better to have local write procedures or a class interface?). Uncoupling the procedural code in a well-thought-out and extensible way is the major obstacle and motivation for the project.
Approach to solving the problem
Currently...
process_args():
bool changes_abi is a flag for ABI changes
bool check_abi_changes() checks for ABI changes
strip_arg_annotations() removes Microsoft SAL and leaves just type
Replaces argument types with respective ABI config types, for padding expansion macros.
Adds processed arguments (type and name) to a table.
Returns table and changes_abi flag.
process_syscall_def = λ:
Calls handle_compat(), handle_noncompat(), etc.
Defines and processes syscall return value.
Has flags, function name, function arguments, etc.
loop write_line() procedure of producing auto-generated files:
handle_compat(), handle_noncompat(), handle_obsol(), handle_reserved() do the bulk of the work
Available data must be sysnum, thr_flag, flags, sysflags, rettype, auditev, funcname, funcalias, funcargs, argalias, syscallret
How to solve:
Much of the heavy lifting will be done in private methods, uncoupling and refactoring individual functionality into methods. More methods can easily be added, achieving the goal of extensibility.
There needs to be separate module subroutines of previous loop write_line() procedure of producing auto-generated files. Common methods will be put into interfaces.
Auto-generation of init_sysent.c, systrace_args.c, sysproto.h has common procedures and should have easily accessible data and shared common methods.
Deliverables
1. System call creation will work as before
2. makesyscalls.lua is refactored into core, modules, and classes
3. System call creation library is easily extensible (It should provide a basis for future system call creation scripts)
4. Well-documented (e.g., "bsd_foo will be generated", how to opt-out of complex generation, etc.)
Milestones
Notable milestones:
- May 27th: Start of coding
- (First week.)
- June 3rd
- (Second week.)
- June 24th - June 28th: Mid-term Evaluation
- July 22nd - July 26th: Final Evaluation
- August 26th: End of coding (soft)
- (complete documentation, etc.)
- September 2nd: End of coding (hard)
(To be reviewed.)
Test Plan
(To be reviewed.)
The Code
To be completed.
Notes
To be completed.
Useful links
Adding Syscalls to FreeBSD:
https://wiki.freebsd.org/AddingSyscalls, so-you-want-to-add-a-system-call.pdf (AsiaBSDCon 2023), So you want to add a system call (Brooks Davis, video)
Brooks Davis’ recent commits: