Tracking issue for breaking changes

[josephlr]

Many issues/PR currently proposed would break the API of this create. This seems reasonable, but we should try to consolidate changes as much as possible. This issue tracks these changes.

Add any breaking changes you're interested in:

• [x] Including PageTableFlags in the result of translate (~#150~ https://github.com/rust-osdev/x86_64/pull/207)
• [x] Rename MapperAllSizes to Translate (https://github.com/rust-osdev/x86_64/issues/152, done in https://github.com/rust-osdev/x86_64/pull/211)
• [x] ~Potentially changing which methods are required and which are provided for Mapper (https://github.com/rust-osdev/x86_64/issues/192)~
  • The suggestion in that issue (a new map_range_with_table_flags with a default implementation) does not require any breaking changes.
• [ ] Remove PhysFrameRange, PhysFrameRangeInclusive, PageRange, PageRangeInclusive to instead use the Rust types.
  • Postponed until Step trait is stable
  • See https://github.com/rust-osdev/x86_64/issues/212
• [x] ~Make PhysToVirt actually map PhysAddr to VirtAddr (instead of returning a pointer) (tried in https://github.com/rust-osdev/x86_64/pull/213, but it doesn't work)~
• [x] Rename PhysToVirt trait to PageTableFrameMapping (https://github.com/rust-osdev/x86_64/pull/214)
• [x] Make DescriptorTablePointer::base a VirtAddr (makes it clear segmentation is applied before paging). (done in https://github.com/rust-osdev/x86_64/pull/215)
• [x] Make read_rip return a VirtAddr (done in https://github.com/rust-osdev/x86_64/pull/216)
• [ ] Use correct types for InterruptStackFrameValue:
  • code_segment should be a SegmentSelector
    • unresolved problem: SegmentSelector is an u16, but the field in InterruptStackFrameValue must be an u64
  • cpu_flags should be a RFlags
  • stack_segment should be a SegmentSelector _-> same problem as for code_segment_
• [x] Remove deprecated items:
  • UnusedPhysFrame
  • ExceptionStackFrame
  • VirtAddr::new_unchecked
• [x] Remove PortReadWrite (it no longer makes sense to have it given the const fn changes to Port) (done in https://github.com/rust-osdev/x86_64/pull/217)
• [x] rflags (done in https://github.com/rust-osdev/x86_64/pull/219)
  • Make write/write_raw unsafe (they can cause instant UB or crashes)
  • Document that reading/writing any of CF, PF, AF, ZF, SF, OF might do weird things (as Rust/LLVM use these flags)
  • Document that a user should never set DF (as it must be unset in all Rust code)
• [x] Use custom error types instead of () (https://github.com/rust-osdev/x86_64/pull/199)
• [x] Also return flags for MapperAllSizes::translate() (https://github.com/rust-osdev/x86_64/pull/207)

[phil-opp]

Sounds good to me!

Make PhysToVirt actually map PhysAddr to VirtAddr (instead of returning a pointer)

You mean changing the function signature to something like fn phys_to_virt(&self, phys_addr: PhysAddr) -> VirtAddr? This would make sense to me. The current signature could become an private function for the MappedPageTable type.

[phil-opp]

(I added https://github.com/rust-osdev/x86_64/pull/199 to the list.)

[phil-opp]

(I added https://github.com/rust-osdev/x86_64/pull/207 to the list)

[phil-opp]

I implemented most changes in the next branch. The two remaining items are:

• Remove PhysFrameRange, PhysFrameRangeInclusive, etc.
  • Not possible until Step trait is stable
  • Implementing the Step trait on nightly only is possible as a non-breaking change
• Use correct types for InterruptStackFrameValue
  • I'm not sure what to do about the segment selectors, which are pushed as u64 even though they are only 16 bit

[mental32]

I'm not sure what to do about the segment selectors, which are pushed as u64 even though they are only 16 bit

Could a padded newtype work?

#[repr(C)]
struct PaddedSegmentSelector {
    inner: SegmentSelector,
    _u16: u16,
    _u32: u32,
}

[phil-opp]

Yes, I think that should work.

Given that most of the items from this issue are done, it might make sense to create separate tracking issues for the two remaining items and then close this one.

[josephlr]

Closing as #262 now tracks the 0.15 release.