1###############################################################
2Add support for block-aligned flash in Internal Trusted Storage
3###############################################################
4
5:Author: Minos Galanakis
6:Organization: Arm Limited
7:Contact: Minos Galanakis <minos.galanakis@arm.com>
8
9Abstract
10========
11
12The proposal is describing a mechanism to enable the use of larger flash
13devices, imposing a requirement for word-aligned full-block program operations,
14in Trusted Firmware-M.
15
16
17Requirements
18============
19
20- Allow page-aligned writes for up to 512 Bytes per page.
21- Guarantee data integrity and power-failure reliability.
22- Do not alter existing supported platform behaviour.
23
24Current implementation
25======================
26
27In the current ITS filesystem design, each filesystem create or write operation
28requires two flash blocks to be updated: first the data block and then the
29metadata block. Buffering is avoided as much as possible to reduce
30RAM requirements.
31
32However, if the ITS_FLASH_PROGRAM_UNIT is 512 Bytes then the data will have to
33stored in a temporary memory location in order to be able to write
34that much data in one-shot.
35
36Proposed implementation overview
37================================
38
391. A new block-sized static buffer should be added to its_flash.c when
40   ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported.
412. Methods calling the flash API such as ``its_flash_write()`` or
42   ``its_flash_block_to_block_move()`` will populate the buffer instead of
43   directly programming the flash.
443. A new method ``its_flash_flush()``, should be provided in order to flush
45   the block buffer to the device.
464. ``its_flash_flush()`` should be called twice: Once after a data block
47   update and once more after the metadata block update is completed.
485. The proposed design should require that the data block update is always
49   completed before the metadata block update starts
506. Writes to the block buffer should be atomic, and guarded against corruption
51   by data from different blocks.
52
53Considerations
54==============
55
56- The proposed implementation will increase the RAM usage of ITS by the size
57  of a block, only for platforms which require block-aligned writes.
58- Currently power-failure is detected by software by incrementing an 8-bit
59  metadata header field (``swap_count``), as the last written byte. When the
60  proposed block-buffer is used, the block is programmed in one-shot and the
61  order the bytes are written on the physical device, is hardware dependent.
62- A set of guarantees are required by the supported flash ECC devices.
63  The device's flash APIs should provide a mechanism to capture and raise
64  incomplete program operations, as well as write bytes in a sequential order.
65
66For example, if a board powers down through a 512 page program operation, the
67next read operation should return an error rather than read invalid data.
68
69Functional flow diagram
70=======================
71
72The logic of the proposal is described in the following diagram
73
74.. code-block:: rst
75
76        |----------------------|
77        |   data write()       |
78        |----------------------|
79        |                      |        |------------------------------|
80    |-> |  its_flash_write  |     --->  | data[] -> its_block_buffer[] |
81    |   |                      |        |------------------------------|
82    |   |----------------------|
83    |   |                      |        |------------------------------------|
84    |   |   its_flash_flush    |  --->  | its_block_buffer[] -> flash dev IO |
85    |   |                      |        |------------------------------------|
86    |   |----------------------|
87    |             |
88    |             ------------------------------------
89    |                                                |
90    |                                                V
91    |   |----------------------|        |--------------------------|
92    |   | data write() complete|        | metadata write() complete|
93    |   |----------------------|        |--------------------------|
94    | <-|  Metadata write()    |                     |
95        |----------------------|                     |
96                                                     V
97                                        |--------------------------|
98                                        |    Operation Complete    |
99                                        |--------------------------|
100
101--------------
102
103*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
104