Add block storage service documentation
Adds a service description for the block storage service.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I3300511f0bdd68b32cb8546332177ae6959c7b29
diff --git a/docs/developer/service-descriptions/block-storage-service-description.rst b/docs/developer/service-descriptions/block-storage-service-description.rst
new file mode 100644
index 0000000..a29f057
--- /dev/null
+++ b/docs/developer/service-descriptions/block-storage-service-description.rst
@@ -0,0 +1,262 @@
+Block Storage Service
+=====================
+Overview
+--------
+The Block Storage service can be used to share a block-oriented storage device
+such as a QSPI flash between a set of independent secure world clients. A block
+storage service provider presents a block level interface for accessing an
+underlying block storage device. To allow multiple higher layer filesystems to
+share the same storage device, logical block addresses are partitioned, based on
+configuration data provided by a system integrator. The partition configuration
+data may be read from a GUID Partition Table (GPT) or from the block storage SP
+manifest. The configuration data restricts access to a storage partition to a
+defined owner. Each owner is allocated a maximum number of blocks and is given
+exclusive access to its own blocks, based on the client ID of the calling client.
+
+The following diagram illustrates a firmware integration that uses a single block
+storage service provider to control access to a dedicated flash device. In this
+example StMM, OP-TEE, Update Agent and the Protected Storage SP act as clients of
+the service. Each client independently manages its own filesystem and is presented
+with its own logical partition, starting with a logical block address (LBA) of zero.
+
+.. image:: image/block-storage-example-usage.svg
+
+Project Directories
+-------------------
+Components within the Trusted Services project related to the Block Storage service
+are located under the following directories:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Directory
+ - Contains
+ * - ``components/service/block_storage``
+ - Service specific code components.
+ * - ``deployments/block-storage``
+ - Build files and deployment specific code for building alternative configurations
+ of the block storage service provider.
+ * - ``protocols/service/block_storage``
+ - Service access protocol definitions.
+
+Service Interface
+-----------------
+The Block Storage service supports a conventional set of block-level operations that
+can be adapted to different driver models by clients. The following table summarizes
+supported operations:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Operation
+ - Description
+ * - Open
+ - Open a session - take the required *UniquePartitionGUID* as a parameter. Returns
+ a handle to be used as a qualifier for other requests made by a client.
+ * - Close
+ - Close a previously opened session.
+ * - GetInfo
+ - Returns information about the partition associated with an open session. Includes
+ the block size and the total number of blocks assigned to the partition.
+ * - Read
+ - Read data from the specified block.
+ * - Write
+ - Write data to the specified block.
+ * - Erase
+ - Erase a set of one or more blocks.
+
+Protocol definitions live under: ``protocols/service/block_storage``.
+
+The service interface is realized by the block storage service provider. It delegates
+storage operations to a backend *block_store*. The *block_store* defines a common
+interface for components that realize block storage operations. Where an underlying storage
+technology does not support an explicit erase operation (e.g. RPMB), the corresponding
+concrete *block_store* should return success for a call to erase but perform no actual
+operation (if the partition is writable and the LBA falls within the limits of the
+partition).
+
+Service Provider Configuration
+------------------------------
+A platform integrator must provide a set of configuration data to configure how the block
+storage service provider presents block storage to clients. Configuration data relates to
+the following:
+
+ - **Storage partition configuration** - determines how storage is divided into separate partitions
+ - **Block device configuration** - determines how the backed storage device is configured
+
+Storage Partition Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The block storage service allows a block storage device to be presented as a single storage
+partition or as a set of smaller storage partitions. The way that storage is presented is
+determined by configuration data prepared by a platform integrator. Each storage partition
+presented by a block storage service provider starts at LBA zero. The number of partitions
+and their size are defined by configuration data. Configuration data assigns partitions
+to owners to enable access to be controlled. If no partition configuration exists for a
+requesting client or if an attempt is made to access a block outside of the configured LBA
+range, access is denied. The set of storage partitions used for secure block storage will
+not necessarily span the entire underlying storage device. A platform integrator is free to
+limit the area used for secure block storage to allow the storage device to be used for other
+purposes e.g. as a boot source, read by the boot loader during early boot stages.
+
+Two partition configuration methods will be supported; one where partition configuration data
+is read from an SP manifest and the other where configuration is defined by a GUID Partition
+Table. Both methods may be used in combination if necessary. Initial implementations will
+use the SP manifest configuration method.
+
+Each partition configuration entry includes an attributes bitmap that conforms to the UEFI
+GPT Partition Entry attributes definition (see section 5.3 of the UEFI specification). Bits
+48-63 are reserved for GUID specific use. For partitions labelled with the Secure Block Store
+GUID, bits will be defined for:
+
+ - **Read-only** - write and erase operations are forbidden.
+
+A GPT partition entry includes the PartitionName property which normally holds a human readable
+name for the partition. For secure block store partitions, the PartitionName property will
+hold the canonical UUID string identifying the owner. An empty string is interpreted as
+'no specific owner' and any client will be granted access.
+
+Configuration via SP Manifest
+"""""""""""""""""""""""""""""
+For an SP deployment, the partition configuration may be read from a device tree blob (DTB),
+passed as an initialization parameter. Per-partition configuration data comprises the following:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Config Value
+ - Description
+ * - UniquePartitionGUID
+ - GUID that is unique for a partition entry.
+ * - StartingLBA
+ - The storage block address corresponding to LBA zero.
+ * - EndingLBA
+ - The last storage block in the contiguous range of blocks.
+ * - Attributes
+ - See UEFI specification
+ * - Owner
+ - Holds canonical UUID string for owner.
+
+The partition configuration is included as a sub-node of the block-dev node that includes
+configuration values related to the block device. The following is an example of how a block
+device and related partitions are defined within a DT based SP manifest::
+
+ block-dev {
+ compatible = "tforg,ts-block-dev"
+ disk-guid = "af9f72de-d71f-4492-b44b-a4b4d96000bf"
+
+ partitions {
+ compatible = "tforg,ts-block-partitions"
+
+ fwu-meta {
+ guid = "a6f99e90-7a75-4384-847a-29c9a86c6279"
+ start-lba = <0x00000000>
+ end-lba = <0x00000003>
+ attr = <0x00000000>
+ owner = "afb995cd-9354-4333-9ea2-bd62ccaedb22"
+ };
+
+ fip {
+ guid = "1eccc9bc-9a5f-43d0-bcd3-466fd21c9a92"
+ start-lba = <0x00000004>
+ end-lba = <0x00040003>
+ attr = <0x00000000>
+ owner = "afb995cd-9354-4333-9ea2-bd62ccaedb22"
+ };
+
+ uefi-var {
+ guid = "1022a92b-4b4a-47b4-94cb-35faf5a45dc2"
+ start-lba = <0x00040004>
+ end-lba = <0x00080003>
+ attr = <0x00000000>
+ owner = "ed32d533-99e6-4209-9cc0-2d72cdd998a7"
+ };
+ };
+ };
+
+Configuration via GUID Partition Table (GPT)
+""""""""""""""""""""""""""""""""""""""""""""
+The UEFI specification defines a standard layout for physical storage devices where storage
+partitions are described by partition entries within the GUID Partition Table. During
+initialization, the Block Storage SP will read the GPT and iterate over partition entries,
+identifying those with the secure block store partition type GUID. Each entry contains the
+following:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Offset
+ - Length
+ - contents
+ * - 0
+ - 16 bytes
+ - PartitionTypeGUID - Secure Block Store GUID
+ * - 16
+ - 16 bytes
+ - UniquePartitionGUID
+ * - 32
+ - 8 bytes
+ - Starting LBA
+ * - 40
+ - 8 bytes
+ - Ending LBA
+ * - 48
+ - 8 bytes
+ - Attributes (e.g. read-only)
+ * - 56
+ - 72 bytes
+ - PartitionName - Holds canonical UUID string for owner.
+
+Design Description
+------------------
+The block storage service provider conforms to the same model as other service providers
+within the TS project. Service requests from clients are received by a service provider
+that is responsible for parameter deserialization/serialization and service level access
+control. Block storage operations are delegated to a backend *block_store* that provides
+block-level storage in some way. There is much flexibility to realize the backend block-level
+storage in different ways, allowing platform integrators to use alternative *block_store*
+realizations to provide storage solutions that meet specific product requirements.
+
+The following class diagram illustrates the block storage service provider model:
+
+.. uml:: uml/BlockStorageProvider.puml
+
+Block Store
+^^^^^^^^^^^
+The *block_store* component defines a virtual interface for block IO operations. Alternative
+concrete *block_store* implementations are supported. Some *block_store* components are stackable
+over other *block_store* components to add features such as store partitioning or block
+authentication. Separation of functionality into stackable *block_store* components gives
+platform integrators the flexibility to create alternative storage solutions with different
+security/cost tradeoffs. The base *block_store* interface is defined in::
+
+ components/service/block_storage/block_store/block_store.h
+
+Components that implement the *block_store* interface are located in subdirectories beneath
+``components/service/block_storage/block_store``. A *block_device* is class of *block_store*
+that actually provides block-level storage. In a stack of *block_store* components, a
+*block_device* will always live at the bottom. The following layer diagram illustrates a
+typical block storage deployment where storage is provided by a stack of *block_store* components:
+
+.. image:: image/block-storage-layers.svg
+
+Some block devices supported in the TS project (located under:
+``components/service/block_storage/block_store/block_device``) are:
+
+ - **ram_block_store** - stores blocks in RAM. Intended for test purposes.
+ - **null_block_store** - a store with no real storage. Always accepts legal writes and returns
+ zeros for reads.
+ - **fvb_block_store** - an adapter that uses a UEFI firmware volume block driver to access
+ storage. Can be used with drivers from the EDK2 project.
+
+Other supported block_store components:
+
+ - **partitioned_block_store** - a stackable *block_store* that presents an underlying *block_store*
+ as a set of configurable storage partitions.
+ - **block_storage_client** - communicates with a remote block storage service provider to provide
+ storage.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/image/block-storage-example-usage.svg b/docs/developer/service-descriptions/image/block-storage-example-usage.svg
new file mode 100644
index 0000000..5da7427
--- /dev/null
+++ b/docs/developer/service-descriptions/image/block-storage-example-usage.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="921px" height="551px" viewBox="-0.5 -0.5 921 551" content="<mxfile host="confluence.arm.com" modified="2022-08-25T16:15:08.782Z" agent="5.0 (X11)" etag="mAY4xjS1y1Ce76DsL9WA" version="20.1.4" type="atlas"><mxAtlasLibraries/><diagram id="plxMLLH-skr558P6A1ZB" name="Page-1">3VrbctowEP0aHunYFubyyDWdJkyY0k5KXjqKLWwNwmJkESBfXxnLV5lLCdSmT1hH0gqdPdr1Cmqgv9w+MLhyx9RGpGZo9rYGBjXD0DsAiI8A2YVIGzRCwGHYloMSYIo/kAQ1ia6xjfzMQE4p4XiVBS3qecjiGQwyRjfZYXNKsquuoCNX1BJgakGClGEv2Oau3IWZGv0VYceNVtY12bOE0WAJ+C606SYFgWEN9BmlPHxabvuIBORFvITzRgd64y/GkMfPmTBv7Zzxyuqw2XjDtfaH/mrCuhFaeYdkLTcsvyzfRQwwuvZsFBjRa6C3cTFH0xW0gt6N8LnAXL4ksnuOCelTQtl+LrAhas8tgfuc0QWKejzqiek9dQdyU++IcbRNQXJHD4guEWc7MUT21vWmpFfqK2J7kzgrHuKmHdWWIJQCcWLbCYfiQdJYTOmju/6tdRmZ6LPm2+IbefrOaF2/d0pblaNUVemUj8dHaNVO03oVphpZppqmypRRwFTnCkQ96QuwaDuzH5OXwSvt9Qh/9O5fe2aZ2iukVNXehFEuUo3g0NCmnLIgg5QuRbNqUgT3LkVQOSk2FEqfJ/Ufw2H56gNVU5957+pTAmG7dPk1FU57hFqLKkdBYJQtxJZC2gDZ2IJh+hgR6LsKbaJSWAWP1o5gwR8Dp8l7C5l+eosBaC2cPf/Pay7MIIn7YYWlm9diXM8y3uioOi2S6c1U2j598pFnd4PSMDmxKSbRFvNfgWK/mLI1k/oNngfbdGOXakwQw2IHiEWYJ3aTMhQ0Z9EaQSMxtW9Ftg46xadrZqHTUuOQOYifPsfIjirfAy5OedAs8GCEMUQgx+/ZernIrXKFCcViZ4mCjFykA3lphBuX09IFrmIpp0UAcpZCahRLe53FG79cep1PSu+g66viKqUybFzoqsYJOzd2VKSTlKdGo3pXIGPk+9DBnqN4TgREnnVXYe5PvyhICBLseEE4F24NwkMvCK8iBZCu7Fhi2w6WKQzy2Rx6hZBt5rgHBS8WeoGIjFtFbP2MqvV4yL52qD0ZQhvVOpdxNv3suVRDaN7rtz6Zarn9b7RwSdq/PFU3z9SZUTGd5VN16251dsb1RHkx59glaFW00Px/Yo56rzKBIkNzTD0B96k3x86awbB9oFazqbVe7n3616XaFXK6cgEDCrJ6p0ANNyvD9DNuYNQDZotyOL6SKSjK9HRsjiN1WdFZr9prwD2G58KfJdU3wp8rG3IksK6D5Jql3jTpJd54FlJW6YR2zMlVOT3Xy2c5Q6Z5pbMjmsnfBcLhyZ8uwPAP</diagram></mxfile>"><defs/><g><rect x="600" y="0" width="160" height="180" rx="24" ry="24" fill="#dae8fc" stroke="none" pointer-events="all"/><rect x="0" y="0" width="160" height="180" rx="24" ry="24" fill="#dae8fc" stroke="none" pointer-events="all"/><rect x="20" y="45" width="120" height="90" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 21px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">StMM</div></div></div></foreignObject><text x="80" y="94" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">StMM</text></switch></g><rect x="200" y="0" width="160" height="180" rx="24" ry="24" fill="#dae8fc" stroke="none" pointer-events="all"/><rect x="220" y="45" width="120" height="90" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 221px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Protected Storage</div></div></div></foreignObject><text x="280" y="94" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Protected Storage</text></switch></g><rect x="400" y="0" width="160" height="180" rx="24" ry="24" fill="#dae8fc" stroke="none" pointer-events="all"/><rect x="420" y="45" width="120" height="90" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 421px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">OP-TEE</div></div></div></foreignObject><text x="480" y="94" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">OP-TEE</text></switch></g><rect x="200" y="260" width="160" height="180" rx="24" ry="24" fill="#dae8fc" stroke="none" pointer-events="all"/><rect x="220" y="305" width="120" height="90" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 350px; margin-left: 221px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Block Storage</div></div></div></foreignObject><text x="280" y="354" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Block Storage</text></switch></g><path d="M 250 485 C 250 476.72 263.43 470 280 470 C 287.96 470 295.59 471.58 301.21 474.39 C 306.84 477.21 310 481.02 310 485 L 310 535 C 310 543.28 296.57 550 280 550 C 263.43 550 250 543.28 250 535 Z" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 310 485 C 310 493.28 296.57 500 280 500 C 263.43 500 250 493.28 250 485" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 523px; margin-left: 251px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Dedicated Flash</div></div></div></foreignObject><text x="280" y="526" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Dedicated...</text></switch></g><path d="M 280 470 L 280 395" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 0 220 L 800 220" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><rect x="810" y="210" width="110" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 220px; margin-left: 811px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">FF-A Messaging</div></div></div></foreignObject><text x="865" y="224" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">FF-A Messaging</text></switch></g><path d="M 480 220 L 480 135" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 280 305 L 280 135" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 220 L 80 135" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 420 310 L 510 310 L 510 378 Q 487.5 356.4 465 378 Q 442.5 399.6 420 378 L 420 322 Z" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 338px; margin-left: 421px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Partition Configuration</div></div></div></foreignObject><text x="465" y="342" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Partition Confi...</text></switch></g><path d="M 340 350 L 420 350" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><rect x="620" y="45" width="120" height="90" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 90px; margin-left: 621px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Update Agent</div></div></div></foreignObject><text x="680" y="94" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Update Agent</text></switch></g><path d="M 680 220 L 680 135" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
\ No newline at end of file
diff --git a/docs/developer/service-descriptions/image/block-storage-layers.svg b/docs/developer/service-descriptions/image/block-storage-layers.svg
new file mode 100644
index 0000000..f7aa6e3
--- /dev/null
+++ b/docs/developer/service-descriptions/image/block-storage-layers.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="701px" height="371px" viewBox="-0.5 -0.5 701 371" content="<mxfile host="confluence.arm.com" modified="2022-09-01T13:39:56.084Z" agent="5.0 (X11)" etag="5wmKJudSRu0eKebtsNFl" version="20.1.4" type="atlas"><mxAtlasLibraries/><diagram id="3S9PIcjPeEhHK4FUF1jD" name="Page-1">7ZhLb+IwEMc/DUdWeROONECrqlXZUmmXvVQmNomLE0eOeWQ//TrEIU8erVK1hz0R/+2M7d/M2BN6uhPsbxmI/EcKEelpCtz39HFP09ShroufVEkyxdCNTPAYhnJQIczxXyRFRaobDFFcGcgpJRxHVdGlYYhcXtEAY3RXHbaipDprBDw5o1IIcxcQ1Bj2C0PuZ6ptlkbfIez5+cyqInsCkA+WQuwDSHclSZ/0dIdRyrOnYO8gksLLuWTvTU/0HhfGUMiveYGrTwYcBM+W9vLzxrRHizeH9aWVLSAbuWG5WJ7kBBjdhBClRtSefrPzMUfzCLhp7074XGg+D4jsXmFCHEooO7yrQ4DslSv0mDO6RqUey7XRciV6mtvI14QYR/uSJLd1i2iAOEvEENnb1wzJWAaZOZDtXeEy3ZaaX3KXlvsRyDDxjsYLkuJBwnwHWKsBdkmou36NOWUiZl4jRrcistkZ3Mpl3J3AU6vwLKUFntYCz/osdvmCSvCeZ8KUMglhRLHY6veD1hJxwxZmqt4BtKe3+3k4DRxk+6OJc+8l1i+/rzeYiR1yzDENEXwtgg99PbzhZXaa8kkB9+dl/fB8a+4WwXj58JhsvMXgvuUUzHhBtMXu9wM2ML4amNYA5hCMzibmt708DLMWjlaTrjpooTv8LLrNVG5wRSEcpdWNaLkExDF2qyirIYr2mP9On38Ylinbi0N7aA9le7wvDR4npcYMMSw2hliuhWKTmTkzby7kvIdGYerQym2ddFZMN8xFl8ONA+YhfsXFgWBe1J3wfcm1Zotnc40hAjjeVkvBNnfLGWbZ5ZSHVu2OGNbP/mzfs+ONNj1hx6rase2anYxLw44IEJCUhh2uzvj0cvv6oDaRqZxdV18V0XTmBfGQraFIhaMPPp4dRiM7piID/EaKiHo7Sh/dhGCRC0y/fAAts6x5WB4F4K69Qy49bbgwg6QeZ98pqtlVOVED33IEWS1xWg+Ezk4gs+sT6OO5n3/0lXL/XFj8T/0uc635FXM6zTaMJDdMJEzqpkuZVq0LVgRHd93VS6p1TYHZ9H0nxXkrx0GDY6UgFzwFtwZasV1exVathEKaHkiVsklKgGAvTJ0iIKb39k0KD7uAjGRHgCFMp2n105Wp+w6H1AtY7brz7QP+EM3iL5UsDYo/pvTJPw==</diagram></mxfile>"><defs/><g><rect x="210" y="0" width="380" height="250" rx="37.5" ry="37.5" fill="#dae8fc" stroke="#6c8ebf" pointer-events="all"/><rect x="240" y="30" width="320" height="60" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 318px; height: 1px; padding-top: 60px; margin-left: 241px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">block_storage_provider</div></div></div></foreignObject><text x="400" y="64" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">block_storage_provider</text></switch></g><rect x="240" y="100" width="90" height="130" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 165px; margin-left: 241px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">RPC Endpoint</div></div></div></foreignObject><text x="285" y="169" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">RPC Endpoint</text></switch></g><rect x="360" y="100" width="200" height="60" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 198px; height: 1px; padding-top: 130px; margin-left: 361px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">partitioned_block_store</div></div></div></foreignObject><text x="460" y="134" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">partitioned_block_store</text></switch></g><rect x="360" y="170" width="200" height="60" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 198px; height: 1px; padding-top: 200px; margin-left: 361px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">block_device</div></div></div></foreignObject><text x="460" y="204" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">block_device</text></switch></g><rect x="0" y="90" width="170" height="90" rx="13.5" ry="13.5" fill="#dae8fc" stroke="#6c8ebf" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 168px; height: 1px; padding-top: 135px; margin-left: 1px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Client</div></div></div></foreignObject><text x="85" y="139" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Client</text></switch></g><path d="M 79.05 179.01 L 80 280 L 285 280 L 285 236.37" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 285 231.12 L 288.5 238.12 L 285 236.37 L 281.5 238.12 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 430 305 C 430 296.72 443.43 290 460 290 C 467.96 290 475.59 291.58 481.21 294.39 C 486.84 297.21 490 301.02 490 305 L 490 355 C 490 363.28 476.57 370 460 370 C 443.43 370 430 363.28 430 355 Z" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 490 305 C 490 313.28 476.57 320 460 320 C 443.43 320 430 313.28 430 305" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 343px; margin-left: 431px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Flash</div></div></div></foreignObject><text x="460" y="346" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Flash</text></switch></g><path d="M 460 230 L 460 283.63" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 460 288.88 L 456.5 281.88 L 460 283.63 L 463.5 281.88 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 630 100 L 625 100 Q 620 100 620 110 L 620 155 Q 620 165 615 165 L 612.5 165 Q 610 165 615 165 L 617.5 165 Q 620 165 620 175 L 620 220 Q 620 230 625 230 L 630 230" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" transform="translate(620,0)scale(-1,1)translate(-620,0)" pointer-events="all"/><rect x="640" y="150" width="60" height="30" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 165px; margin-left: 641px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">block_store stack</div></div></div></foreignObject><text x="670" y="169" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">block_stor...</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
\ No newline at end of file
diff --git a/docs/developer/service-descriptions/index.rst b/docs/developer/service-descriptions/index.rst
index 6574a3e..9814958 100644
--- a/docs/developer/service-descriptions/index.rst
+++ b/docs/developer/service-descriptions/index.rst
@@ -8,6 +8,7 @@
attest-service-description
crypto-service-description
secure-storage-service-description
+ block-storage-service-description
uefi-smm-services
--------------
diff --git a/docs/developer/service-descriptions/uml/BlockStorageProvider.puml b/docs/developer/service-descriptions/uml/BlockStorageProvider.puml
new file mode 100644
index 0000000..4f26b2f
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/BlockStorageProvider.puml
@@ -0,0 +1,45 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+class rpc_interface {
+ +rpc_status_t {abstract}receive(call_req)
+}
+
+class service_provider {
+ +void init(handlers, num_handlers)
+ +void extend(service_provider)
+ -rpc_status_t receive(call_req)
+}
+
+class block_storage_provider {
+ +void init(block_store)
+ +void regsiter_serializer(encoding, serializer)
+ -rpc_status_t open_handler(call_req)
+ -rpc_status_t close_handler(call_req)
+ -rpc_status_t get_partition_info_handler(call_req)
+ -rpc_status_t read_handler(call_req)
+ -rpc_status_t write_handler(call_req)
+ -rpc_status_t erase_handler(call_req)
+}
+
+class block_store {
+ +int {abstract}open(client_id, uuid, *handle)
+ +int {abstract}close(handle)
+ +int {abstract}get_partition_info(uuid, *partition_info)
+ +int {abstract}read(handle, lba, size, *buffer, *len)
+ +int {abstract}write(handle, lba, *buffer, len)
+ +int {abstract}erase(handle, *lba, num_blocks)
+}
+
+service_provider -up--|> rpc_interface
+block_storage_provider -up--|> service_provider
+block_storage_provider --> block_store
+block_storage_provider --> block_storage_serializer
+
+@enduml