Thanks to visit codestin.com
Credit goes to github.com

Skip to content

capsules: remove doc leftovers on SyscallDriver impls #3532

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 11 commits into from
Sep 5, 2023
Merged

capsules: remove doc leftovers on SyscallDriver impls #3532

merged 11 commits into from
Sep 5, 2023

Conversation

elenaf9
Copy link
Contributor

@elenaf9 elenaf9 commented Jul 2, 2023 •
edited
Loading

Pull Request Overview

In #2639 subscribe was remove from the SyscallDriver trait, and in #2906 also allow_readwrite and allow_readonly were removed.
Both PRs however left some of the code docs related to the removed functions. I am not sure if that was intentional, but it confused me quite a bit when I was looking into the code.

This PR proposes to remove these old docs. But I am quite new to tock, so maybe I am missing something and there was a reason for keeping them?

Testing Strategy

Not relevant._

TODO or Help Wanted

Open Questions:

  • Is any information lost by removing the docs?
  • Are there any other related docs that should be updated?

Documentation Updated

  • Updated the relevant files in /docs, or no updates are required.

Formatting

  • Ran make prepush.
Fails due to an unrelated error in `kernel/src/process_standard.rs:535:13` 
error[E0308]: mismatched types
   --> kernel/src/process_standard.rs:535:13
    |
530 |         Some(storage_permissions::StoragePermissions::new(
    |              -------------------------------------------- arguments to this function are incorrect
...
535 |             write_id,
    |             ^^^^^^^^ expected `Option<NonZeroU32>`, found `Option<u32>`
    |
    = note: expected enum `Option<NonZeroU32>`
               found enum `Option<u32>`
note: associated function defined here
   --> kernel/src/storage_permissions.rs:49:19
    |
49  |     pub(crate) fn new(
    |                   ^^^
...
54  |         write_id: Option<NonZeroU32>,
    |         ----------------------------

@bradjc
Copy link
Contributor

bradjc commented Jul 2, 2023

We did intentionally keep them. Even though the capsules are no longer implementing the logic for storing the process buffers, the contract between userspace and the capsule for how the buffers are used is still implemented in the capsule.

Now, the rewrite in those PRs was fairly substantial, and we didn't put really any effort in to what to do with those comments, other than not delete them. If there is some way we would keep the documentation but reduce the confusion that would be ideal.

@elenaf9
Copy link
Contributor Author

elenaf9 commented Jul 3, 2023 •
edited
Loading

If there is some way we would keep the documentation but reduce the confusion that would be ideal.

👍 I'll try to come up with something.

@alevy
Copy link
Member

alevy commented Jul 5, 2023

Thanks @elenaf9! The current documentation is indeed confusing now. Perhaps there is a way to refer to some central documentation of the semantics of each high-level system call (allow_read, subscribe, etc) but keeping the specific use of each subdriver number in the drivers themselves, by convention.

@bradjc
Copy link
Contributor

bradjc commented Jul 31, 2023

I think we should just move these to the top of the files.

@bradjc bradjc force-pushed the capsules/syscall-drivers-docs branch from 3427b2c to 3c9b3d3 Compare August 31, 2023 00:06
@bradjc
Copy link
Contributor

bradjc commented Aug 31, 2023

Ok this should be ready to go.

@bradjc bradjc force-pushed the capsules/syscall-drivers-docs branch from 3c9b3d3 to 19a987f Compare August 31, 2023 02:34
@ppannuto ppannuto added this pull request to the merge queue Sep 5, 2023
Merged via the queue into tock:master with commit 6b99f9d Sep 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ppannuto ppannuto ppannuto approved these changes

@lschuermann lschuermann lschuermann approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@elenaf9 @bradjc @alevy @ppannuto @lschuermann