PCR 15230 - Improve the documentation and user experience with mapViewOfPlatformResource() is used on striped resources
Summary: Improve the documentation and user experience with mapViewOfPlatformResource(...
Status: ASSIGNED
Alias: None
Product: Kernel
Classification: Deos
Component: Kernel (show other PCRs)
Version: mainline
Hardware: All Deos
: Any Upcoming
: Enhancement
Target Milestone: mainline
Assignee: .Kernel
URL:
Whiteboard:
Depends on:
Blocks:
 
Reported: 2023-10-17 12:00 MST by rroffelsen
Modified: 2024-12-11 13:05 MST (History)
2 users (show)

See Also:
Impact Assessment: Light
Organization: DDC-I, Inc.
amartinez: Requirements+
amartinez: Code+
rroffelsen: TestCases?
rroffelsen: TestProcedures?
rroffelsen: Other?


Attachments

Note You need to log in before you can comment on or make changes to this PCR.
Description rroffelsen 2023-10-17 12:00:21 MST
When dealing with striped platform resources the mapViewOfPlatformResource() UG documentation of resource length versus size is not clear. Note: the SRD is clear.

Also it would be helpful if getPlatformResourceAttributes() (or some other API) provided the mappable size of a striped resource. If not, then at a minimum the equation for the mappable size of the striped resource should be provided.
Comment 1 Andre Martinez 2023-11-13 15:43:38 MST
Committed SVNRevision 90685.

Adding new attribute to platformResourceAttributes_t, userMappableSizeInBytes. Update getPlatformResourceAttributes() accordingly.
Comment 2 Ronald Rische 2023-11-13 16:10:58 MST
(In reply to Andre Martinez from comment #1)
> Committed SVNRevision 90685.
> 
> Adding new attribute to platformResourceAttributes_t,
> userMappableSizeInBytes. Update getPlatformResourceAttributes() accordingly.

Detection of 'isStriped' might be more accurately stated as not equal to zero rather than greater than zero.
Comment 3 Andre Martinez 2023-11-13 16:20:48 MST
Committed SVNRevision 90688.

Incorporate feedback from comment #2.
Comment 4 rroffelsen 2023-11-14 06:27:52 MST
(In reply to Andre Martinez from comment #1)
> Committed SVNRevision 90685.

The following is not correct:
  userMappableSizeInBytes = (r->accessRights == proxyAccess) ? 0 : r->lengthInBytes;

accessRights is of type resourcePermissionBits, not accessStyle (the enum type that  defines proxyAccess). The registry does not specify if a resource must be accessed as proxy or not, this determined at resource construction time (see PR_ConceptualObjectConstructor()). 

We don't want to duplicate the proxy determination code in PR_ConceptualObjectConstructor() nor do I see a good way to refactor the code so it could be shared. 

Perhaps another solution is to rename userMappableSizeInBytes to usableSizeInBytes (or perhaps even just sizeInBytes because once this PCR is finished the UG should clearly document the difference between a resource's "length" and its "size"). If we do this then need for the proxy check goes away.
Comment 5 Andre Martinez 2023-11-14 08:14:55 MST
Committed SVNRevision 90692.

Changing userMappableSizeInBytes to just sizeInBytes.
Comment 6 Andre Martinez 2023-11-14 08:21:03 MST
Committed SVNRevision 90694.

Add comments to previous commit.
Comment 7 Andre Martinez 2023-11-14 14:14:19 MST
Committed SVNRevision 90705.

Clarify difference between resource length and size. Adding clarification to the Platform Resource Services section instead.
Comment 8 deosbugs.ccb 2024-01-23 15:34:29 MST
CCB visited this PCR on 2024-01-23-80895
Comment 9 deosbugs.ccb 2024-01-23 15:58:39 MST
Developer asserts updates are acceptable for release 11.1.0.
Comment 10 deosbugs.ccb 2024-04-04 13:19:50 MST
CCB visited this PCR on 2024-04-04-71881
Comment 11 deosbugs.ccb 2024-08-30 06:56:05 MST
CCB visited this PCR on 2024-08-30-49739
Comment 12 deosbugs.ccb 2024-08-30 07:34:17 MST
Developer asserts updates are acceptable for release 11.4.0.
Comment 13 deosbugs.ccb 2024-12-11 13:05:26 MST
CCB visited this PCR on 2024-12-11-68907