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:

• Including PageTableFlags in the result of translate (#150 feat(paging): Also return flags for MapperAllSizes::translate() #207)
• Rename MapperAllSizes to Translate (Rename MapperAllSizes to Translate? #152, done in Restructure the TranslateResult type and create separate Translate trait #211)
• Potentially changing which methods are required and which are provided for Mapper (Add Mapper methods to map PageRange to PhysFrameRange #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 Implement core::iter::Step for PhysFrame and Page #212
• Make PhysToVirt actually map PhysAddr to VirtAddr (instead of returning a pointer) (tried in Change signature of PhysToVirt::phys_to_virt #213, but it doesn't work)
• Rename PhysToVirt trait to PageTableFrameMapping (Rename PhysToVirt trait to PageTableFrameMapping #214)
• Make DescriptorTablePointer::base a VirtAddr (makes it clear segmentation is applied before paging). (done in Make DescriptorTablePointer::base a VirtAddr #215)
• Make read_rip return a VirtAddr (done in Change return type of read_rip to VirtAddr #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
• Remove deprecated items:
  • UnusedPhysFrame
  • ExceptionStackFrame
  • VirtAddr::new_unchecked
• Remove PortReadWrite (it no longer makes sense to have it given the const fn changes to Port) (done in Remove PortReadWrite trait, which is no longer needed #217)
• rflags (done in Make writing the RFLAGS register unsafe #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)
• Use custom error types instead of () (Use custom error types instead of () #199)
• Also return flags for MapperAllSizes::translate() (feat(paging): Also return flags for MapperAllSizes::translate() #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 #199 to the list.)

[phil-opp]

(I added #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.