Skip to content
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

doc: add information about types used in the kernel #53

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

doc: add information about types used in the kernel #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@
- [Startup](./doc/startup.md)
- [Syscalls](./doc/syscalls.md)
- [Tock Binary Format](./doc/tock_binary_format.md)
- [Types](./doc/types.md)
- [Module Documentation](./doc/modules.md)
- [Process Console](./doc/pconsole.md)
- [Networking Stack](./doc/networking_stack.md)
Expand Down
30 changes: 30 additions & 0 deletions src/doc/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Types

Certain types within the Tock kernel are chosen very deliberately. This aids
with clarity on how the kernel works and helps with porting to new platforms.

## Integer Types

Many kernel interfaces use integer types (e.g., `usize` or `u32`). These types
are often used because the contained value must fit in a hardware register,
represents a memory address, or is a fixed width in an interface specification.
The kernel should use these types very deliberately depending on the meaning of
the underlying value.

- Fixed-width integers (e.g., `u32`, `u8`, etc.): These types should be used
when the value is meant to be precisely the specified number of bits and the
width restriction has a particular semantic meaning. For example, this could
be a timer value used within a system call interface, or a field in a TBF
header.
- Machine-sized types (e.g., `usize`): These types should be used for a value
that should fit exactly into a register, like a abstract argument to the
`command` syscall.
Comment on lines +19 to +21
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this example really what we want to have? Way back when we talked about this for the 2.0 system call interface, we converged on having the current system call interface and driver traits use u32s consistently, and implement an additional, 64-bit specific trait for such platforms when we have them. I know that at least for command args, we're currently not living this reality, though we arguably ought to be.

I still think this is a good idea, because this way we don't have to reason about edge-cases on different platforms for the system call interface. Driver (interfaces) behave identically across these platforms.

I'll have to check whether the CHERI PR (tock/tock#4174) changes this.

- Constant pointer (e.g., `*const u8`): These types should be used for a value
that refers to an address but userspace does not have access to. For example,
this could be the intended new boundary of the heap after calling `brk`.
- Authenticated pointer (e.g., `AuthenticatedPtr`): This type should be used for
a pointer that is provided to userspace. These pointers, on some systems,
include additional information which allows userspace to dereference the
pointer. On other systems this behaves as a traditional pointer. With any
underlying implementation, this type expresses that the value is a pointer
that userspace uses.