Heads-up about pending block-API changes

[Norman Feske]

Hello everyone,

hereby, I'd like to raise your awareness about pending API changes that
affect block-level components. I post this here because block-level
components outside our source tree will need an adaptation to the new API.

The change consists of two parts, one for the server side and one of the
client side. Both parts are already on our staging branch and will reach
the master branch soon.

The new server-side API is located at
'os/include/block/request_stream.h'. It is already part of Genode 19.02
but remained largely unused at the point of the release. In contrast to
the traditional API at 'os/include/block/component.h', the new API
anticipates the design of block services as state machines and is
designed for the efficient batched processing of block operations. You
can find an illustrative example of a block server using this API at
'os/src/test/block_request_stream'.

The new client-side API has become part of the 'Block::Connection'
located in 'os/include/block_session/connection.h'. Like the server-side
API, it is designed for an asynchronous and batched mode of operation.
It achieves this with the added notion of 'Job' objects associated to a
connection. For more details, you can find the corresponding issue at
[1]. The first component I updated to the new API is the block tester
located at 'os/src/app/block_tester/'. So there is already a nice
playground in the form of the block_tester.run and
block_request_stream.run scripts, both located at 'os/run/'.

[1] https://github.com/genodelabs/genode/issues/3283

The client-side as well as the server-side APIs completely hide the
underlying packet stream mechanism so that we can - in the future once
all components are migrated to the new API - simplify this transport
mechanism. By hiding the packet stream, components become much simpler
because the application code is no longer bothered with the handling of
packet-stream corner cases.

If you maintain custom block-level components, I hereby encourage you
giving the new API a try and report your findings. At the current time,
the original APIs are still maintained. So there can be smooth
transition phase. Still, a few cosmetic adaptations even in the case of
intermediately sticking to the old API are needed.

* 'Block::Connection' has become a template. To make your code compile
  again, the default template argument may become handy. Just rename
  the type to 'Block::Connection<>'.

* The 'Block::Session::info' RPC function has a new signature. Instead
  of using C-ish out parameters, the new version returns a compound
  object of type 'Info'.

* The original 'Block::Session::Operations' type is gone. In practice,
  it was merely used to distinguished read-only from read-writeable
  block devices. Now, it has been superseded with a 'writeable'
  attribute of the 'Info' type. Much simpler.

* SYNC and TRIM have become first-class asynchronous block operations.
  The former 'sync' RPC function does not exist anymore.

I hope you like the direction for the API changes. Your feedback is very
welcome. If this direction turns out well, we may take the design as
blue print for other asynchronous inter-component communication APIs
(NIC and file system come in mind) in the future.

Cheers
Norman

-- 
Dr.-Ing. Norman Feske
Genode Labs

https://www.genode-labs.com · https://genode.org

Genode Labs GmbH · Amtsgericht Dresden · HRB 28424 · Sitz Dresden
Geschäftsführer: Dr.-Ing. Norman Feske, Christian Helmuth