class Server

Gets the physical address and length of any secure heap whose physical

range is configured via the TEE.

Presently, these will be fixed physical addresses and lengths, with the

location plumbed via the TEE.

This is preferred over ['fuchsia.hardware.sysmem.Sysmem/RegisterHeap']

when there isn't any special heap-specific per-VMO setup or teardown

required.

The physical range must be secured/protected by the TEE before the

securemem driver responds to this request with success.

Sysmem should only call this once. Returning zero heaps is not a

failure.

Errors:

* PROTOCOL_DEVIATION - called more than once.

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* other errors are allowed; any other errors should be treated the same

as UNSPECIFIED.

Gets information about any secure heaps whose physical pages are not

configured by the TEE, but by sysmem.

Sysmem should only call this once. Returning zero heaps is not a

failure.

Errors:

* PROTOCOL_DEVIATION - called more than once.

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* other errors are allowed; any other errors should be treated the same

as UNSPECIFIED.

This request from sysmem to the securemem driver gets the properties of

a protected/secure heap.

This only handles heaps with a single contiguous physical extent.

The heap's entire physical range is indicated in case this request needs

some physical space to auto-detect how many ranges are REE-usable. Any

temporary HW protection ranges will be deleted before this request

completes.

Errors:

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* other errors are allowed; any other errors should be treated the same

as UNSPECIFIED.

This request from sysmem to the securemem driver conveys a physical

range to add, for a heap whose physical range(s) are set up via

sysmem.

Only sysmem can call this because only sysmem is handed the client end

of a FIDL channel serving this protocol, via RegisterSecureMem(). The

securemem driver is the server end of this protocol.

The securemem driver must configure all the covered offsets as protected

before responding to this message with success.

On failure, the securemem driver must ensure the protected range was not

created.

Sysmem must only call this up to once if dynamic_protection_ranges

false.

If dynamic_protection_ranges is true, sysmem can call this multiple

times as long as the current number of ranges never exceeds

max_protected_range_count.

The caller must not attempt to add a range that matches an

already-existing range. Added ranges can overlap each other as long as

no two ranges match exactly.

Errors:

* PROTOCOL_DEVIATION - called more than once when

!dynamic_protection_ranges. Adding a heap that would cause overall

heap count to exceed max_protected_range_count. Unexpected heap, or

range that doesn't conform to protected_range_granularity. See log.

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* other errors are possible, such as from communication failures or

server propagation of failures.

This request from sysmem to the securemem driver conveys a physical

range to delete, for a heap whose physical range(s) are set up via

sysmem.

Only sysmem can call this because only sysmem is handed the client end

of a FIDL channel serving this protocol, via RegisterSecureMem(). The

securemem driver is the server end of this protocol.

The securemem driver must configure all the covered offsets as not

protected before responding to this message with success.

On failure, the securemem driver must ensure the protected range was not

deleted.

Sysmem must not call this if dynamic_protection_ranges false.

If dynamic_protection_ranges is true, sysmem can call this repeatedly,

on various ranges that exist at the time of the call.

If any portion of the range being deleted is not also covered by another

protected range, then any ongoing DMA to any part of the entire range

may be interrupted / may fail, potentially in a way that's disruptive to

the entire system (bus lockup or similar, depending on device details).

Therefore, the caller must ensure that no ongoing DMA is occurring to

any portion of the range being deleted, unless the caller has other

active ranges covering every block of the range being deleted. Ongoing

DMA to/from blocks outside the range being deleted is never impacted by

the deletion.

Errors:

* PROTOCOL_DEVIATION - called when !dynamic_protection_ranges.

Unexpected heap, or range that doesn't conform to

protected_range_granularity.

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* NOT_FOUND - the specified range is not found.

* other errors are possible, such as from communication failures or

server propagation of failures.

This request from sysmem to the securemem driver conveys a physical

range to modify and its new base and length, for a heap whose physical

range(s) are set up via sysmem.

Only sysmem can call this because only sysmem is handed the client end

of a FIDL channel serving this protocol, via RegisterSecureMem(). The

securemem driver is the server end of this protocol.

The securemem driver must configure the range to cover only the new

offsets before responding to this message with success.

On failure, the securemem driver must ensure the range was not changed.

Sysmem must not call this if dynamic_protection_ranges false. Sysmem

must not call this if !is_mod_protected_range_available.

If dynamic_protection_ranges is true, sysmem can call this repeatedly,

on various ranges that exist at the time of the call.

The range must only be modified at one end or the other, but not both.

If the range is getting shorter, and the un-covered blocks are not

covered by other active ranges, any ongoing DMA to the entire range

that's geting shorter may fail in a way that disrupts the entire system

(bus lockup or similar), so the caller must ensure that no DMA is

ongoing to any portion of a range that is getting shorter, unless the

blocks being un-covered by the modification to this range are all

covered by other active ranges, in which case no disruption to ongoing

DMA will occur.

If a range is modified to become

<

= zero length, the range is deleted.

Errors:

* PROTOCOL_DEVIATION - called when !dynamic_protection_ranges.

Unexpected heap, or old_range or new_range that doesn't conform to

protected_range_granularity, or old_range and new_range differ in

both begin and end (disallowed).

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* NOT_FOUND - the specified range is not found.

* other errors are possible, such as from communication failures or

server propagation of failures.

Zero a sub-range of a currently-existing physical range added via

AddSecureHeapPhysicalRange(). The sub-range must be fully covered by

exactly one physical range, and must not overlap with any other

physical range.

is_covering_range_explicit - When true, the covering range must be one

of the ranges explicitly created via AddSecureHeapPhysicalRange(),

possibly modified since. When false, the covering range must not

be one of the ranges explicitly created via

AddSecureHeapPhysicalRange(), but the covering range must exist as

a covering range not created via AddSecureHeapPhysicalRange(). The

covering range is typically the entire physical range (or a range

which covers even more) of a heap configured by the TEE and whose

configuration is conveyed to sysmem via GetPhysicalSecureHeaps().

Ongoing DMA is not disrupted by this request.

Errors:

* PROTOCOL_DEVIATION - called when !dynamic_protection_ranges.

Unexpected heap.

* UNSPECIFIED - generic internal error (such as in communication

with TEE which doesn't generate zx_status_t errors).

* other errors are possible, such as from communication failures or

server propagation of failures.

|bind_handler| returns a handler that binds incoming connections to this

server implementation.

The returned handler borrows the server instance.

The server must outlive the provided |dispatcher|. Only after

the dispatcher is shutdown will it be safe to destroy the servers.

The server should not be moved.