tock / libtock-rs

Rust userland library for Tock

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Allow-related item naming convention

jrvanwhy opened this issue · comments

The Tock 2.0 syscall TRD calls the Allow system calls "Read-Only Allow" and "Read-Write Allow". Based on these names, I named the constants for them RO_ALLOW and RW_ALLOW.

However, the kernel's SyscallDriver trait names the corresponding functions allow_readonly and allow_readwrite.

In a certain sense, putting "allow" before RO/RW makes sense, as it causes them to be grouped together when sorted alphabetically. This doesn't currently make a difference, but may make a difference if another RO/RW system call is added in the future.

There's also the concern of expansion versus abbreviation. If we don't abbreviate, then we'll end up with some really verbose code and filenames (e.g. allow_readonly_impl_tests.rs), and RO/RW are unlikely to confuse contributors. On the other hand, abbreviation isn't Tock's usual style.

I'm opening this issue to gather opinions on how we should style Allow-related names. To start off, I suggest the following conventions:

  1. In libtock_platform::constants, rename them to ALLOW_RO and ALLOW_RW.
  2. In libtock_platform::syscalls, name the methods allow_ro_* and allow_rw_* (there will be multiple methods for each type of Allow).
  3. In libtock_unittest::fake::Driver, call them allow_readonly and allow_readwrite, to mirror the kernel's SyscallDriver trait.
  4. In module names and filenames, use the abbreviated allow_ro/allow_rw forms.

@hudson-ayers and @alistair23 , what do you think?

I am in favor of exactly what you described

FWIW I agree grouping them by their "broader class" (i.e. stating with allow) makes sense both alphabetically and semantically.

This renaming was implemented in #326.