Skip to content

Commit

Permalink
Add a challenge for btree::node module
Browse files Browse the repository at this point in the history
  • Loading branch information
zhassan-aws committed Jun 26, 2024
1 parent 52bea58 commit b64f99d
Showing 1 changed file with 69 additions and 0 deletions.
69 changes: 69 additions & 0 deletions doc/src/challenges/0004-btree-node.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Challenge 4: Verify the memory safety of the `alloc::collections::btree::node` module

- **Status:** Open
- **Tracking Issue:** [Link to issue](https://github.com/model-checking/verify-rust-std/issues/25)
- **Start date:** *2024-07-01*
- **End date:** *2024-12-10*

-------------------


## Goal

Verify the memory safety of the [`alloc::collections::btree::node` module](https://github.com/rust-lang/rust/blob/c290e9de32e8ba6a673ef125fde40eadd395d170/library/alloc/src/collections/btree/node.rs).
This is one of the main modules used for implementing the `BTreeMap` collection, and it includes a lot of unsafe code.

After annotating functions in this module with their safety contract and verifying those contracts, verify that their usage from `BTreeMap` satisfies the contracts.

### Success Criteria

All public functions (especially safe ones) containing unsafe code must be annotated with safety contracts and the contracts have been verified, e.g.:

1. `LeafNode::new`
1. `NodeRef::new_internal`
1. `NodeRef::as_internal_mut`
1. `NodeRef::len`
1. `NodeRef::ascend`
1. `NodeRef::first_edge`
1. `NodeRef::last_edge`
1. `NodeRef::first_kv`
1. `NodeRef::last_kv`
1. `NodeRef::into_leaf`
1. `NodeRef::keys`
1. `NodeRef::as_leaf_mut`
1. `NodeRef::into_leaf_mut`
1. `NodeRef::as_leaf_dying`
1. `NodeRef::pop_internal_level`
1. `NodeRef::push`
1. `Handle::left_edge`
1. `Handle::right_edge`
1. `Handle::left_kv`
1. `Handle::right_kv`
1. `Handle::insert_recursing`
1. `Handle::descend`
1. `Handle::into_kv`
1. `Handle::key_mut`
1. `Handle::into_val_mut`
1. `Handle::into_kv_mut`
1. `Handle::into_kv_valmut`
1. `Handle::kv_mut`
1. `BalancingContext::do_merge`
1. `BalancingContext::merge_tracking_child_edge`
1. `BalancingContext::steal_left`
1. `BalancingContext::steal_right`
1. `BalancingContext::bulk_steal_left`
1. `BalancingContext::bulk_steal_right`

The usage of the above functions in `BTreeMap` is proven safe.

### List of UBs

All proofs must automatically ensure the absence of the following [undefined behaviors](https://github.com/rust-lang/reference/blob/142b2ed77d33f37a9973772bd95e6144ed9dce43/src/behavior-considered-undefined.md):

* Accessing (loading from or storing to) a place that is dangling or based on a misaligned pointer.
* Reading from uninitialized memory except for padding or unions.
* Mutating immutable bytes.
* Producing an invalid value

Note: All solutions to verification challenges need to satisfy the criteria established in the [challenge book](../general-rules.md)
in addition to the ones listed above.

0 comments on commit b64f99d

Please sign in to comment.