README.md
1Virtual PNOR Functionality
2==========================
3
4In the abstract, the virtual PNOR function shifts mboxd away from accessing raw
5flash to dynamically presenting a raw flash image to the host from a set of
6backing files.
7
8Enabling the feature virtualises both the host's access to the flash (the mbox
9protocol), and the BMC's access to the flash (via some filesystem on top of the
10flash device).
11
12Do I want to use this feature in my platform?
13---------------------------------------------
14
15Maybe. It depends on how the image construction is managed, particularly the
16behaviour around writes from the host. It is likely the scheme will prevent
17firmware updates from being correctly applied when using flash tools on the
18host.
19
20Use-case Requirements
21---------------------
22
23Currently, the virtual PNOR implementation requires that:
24
25* The host expect an FFS layout (OpenPOWER systems)
26* The BMC provide a directory tree presenting the backing files in a hierarchy
27 that reflects the partition properties in the FFS table of contents.
28
29Implementation Behavioural Properties
30-------------------------------------
31
321. The FFS ToC defines the set of valid access ranges in terms of partitions
332. The read-only property of partitions is enforced
343. The ToC is considered read-only
354. Read access to valid ranges must be granted
365. Write access to valid ranges may be granted
376. Access ranges that are valid may map into a backing file associated with
38 the partition
397. A read of a valid access range that maps into the backing file will render
40 the data held in the backing file at the appropriate offset
418. A read of a valid access range that does not map into the backing file will
42 appear erased
439. A read of an invalid access range will appear erased
4410. A write to a valid access range that maps into the backing file will update
45 the data in the file at the appropriate offset
4611. A write to a valid access range that does not map into the backing file
47 will expand the backing file to accommodate the write.
4812. A write to a valid access range may fail if the range is not marked as
49 writeable. The error should be returned in response to the request to open
50 the write window intersecting the read-only range.
5113. A write of an invalid access range will return an error. The error should
52 be returned in response to the request to open the write window covering
53 the invalid range.
54
55The clarification on when the failure occurs in points 11 and 12 is useful for
56host-side error handling. Opening a write window gives the indication that
57future writes are expected to succeed, but in both cases we define them as
58always failing. Therefore we should not give the impression to the host that
59what it is asking for can be satisfied.
60