Overview

This document contains the detail level design for the Layout DB Module.

Purpose of the Layout-DB DLD
The purpose of the Layout-DB Detailed Level Design (DLD) specification is to:

Refine the higher level design
To be verified by inspectors and architects
To guide the coding phase

Definitions

COB: COB is component object For documentation links, please refer to this file : doc/motr-design-doc-list.rst

M0 Glossary

Requirements

The specified requirements are as follows:

R.LAYOUT.SCHEMA.Layid: Layout identifiers are unique globally in the system, and persistent in the life cycle.
R.LAYOUT.SCHEMA.Types There are multiple layout types for different purposes: SNS, block map, local raid, de-dup, encryption, compression, etc.
R.LAYOUT.SCHEMA.Formulae
- Parameters: Layout may contain sub-map information. Layout may contain some formula, and its parameters and real mapping information should be calculated from the formula and its parameters.
- Garbage Collection: If some objects are deleted from the system, their associated layout may still be left in the system, with zero user count. This layout can be re-used, or be garbage collected in some time.
R.LAYOUT.SCHEMA.Sub-Layouts: Sub-layouts.

Dependencies

Layout is a managed resource and depends upon Resource Manager.
Layout DB module depends upon the Layout module since the Layout module creates the layouts and uses/manages them.
Layout DB module depends upon the DB5 interfaces exposed by Motr since the layouts are stored using the DB5 data-base.

Design Highlights

Layout and layout-id are managed resources.
See also
Layouts.
The Layout DB module provides support for storing layouts with multiple layout types.
It provides support for storing composite layout maps.
It is required that for adding a layout type or layout enumeration type, central layout.h should not require modifications.
It is assumed that the problem of coruption is going to be attacked generically at the lower layers (db and fop) transparently, instead of adding magic numbers and check-sums in every module. Thus the input to Layout DB APIs which is either a layout or a FOP buffer in most of the cases is going to be tested for corruption by db or fop layer, as applicable.

Logical Specification

Layout DB makes use of the DB5 data-base to persistently store the layout entries. This section describes how the Layout DB module works.

Component Overview

The following diagram shows the internal components of the "Layout" module, including the "Layout DB" component.

Layout Schema Design

The layout schema for the Layout DB module consists of the following tables.

Key-Record structures for these tables are described below.

Table layouts

* Table Name: layouts
* Key: layout_id
* Record:
*    - layout_type_id
*    - user_count
*    - layout_type_specific_data (optional)
*
*

layout_type_specific_data field is used to store layout type or layout enum type specific data. Structure of this field varies accordingly. For example:

In case of a layout with PDCLUST layout type, the structure m0_layout_pdclust_rec is used to store attributes like enumeration type id, N, K, P.
In case of a layout with LIST enum type, an array of m0_fid structure with size LDB_MAX_INLINE_COB_ENTRIES is used to store a few COB entries inline into the layouts table itself.
It is possible that some layouts do not need to store any layout type or layout enum type specific data in the layouts table. For example, a layout with COMPOSITE layout type.

Table cob_lists

* Table Name: cob_lists
* Key:
*    - layout_id
*    - cob_index
* Record:
*    - cob_id
*
*

This table contains multiple COB identifier entries for every PDCLUST type of layout with LIST enumeration type.

layout_id is a foreign key referring record, in the layouts table.

cob_index for the first entry in this table will be the continuation of the index from the array of m0_fid structures stored inline in the layouts table.

Layout-DB-lspec-schema-comp_layout_ext_map

Table comp_layout_ext_map

* Table Name: comp_layout_ext_map
* Key
*    - composite_layout_id
*    - last_offset_of_segment
* Record
*    - start_offset_of_segment
*    - layout_id
*
*

composite_layout_id is the layout_id for the COMPOSITE type of layout, stored as key in the layouts table.

layout_id is a foreign key referring record, in the layouts table.

Layout DB uses a single m0_emap instance to implement the composite layout extent map viz. comp_layout_ext_map. This table stores the "layout segment to sub-layout id mappings" for each compsite layout.

Since prefix (an element of the key for m0_emap) is required to be 128 bit in size, layout id (unit64_t) of the composite layout is used as a part of the prefix (struct layout_prefix) to identify an extent map belonging to one specific composite layout. The lower 64 bits are currently unused (fillers).

An example:

Suppose a layout L1 is of the type composite and constitutes of 3 sub-layouts say S1, S2, S3. These sub-layouts S1, S2 and S3 use the layouts with layout id L11, L12 and L13 respectively.

In this example, for the composite layout L1, the comp_layout_ext_map table stores 3 layout segments viz. S1, S2 and S3. All these 3 segments are stored in the form of ([A, B), V) where:

A is the start offset from the layout L1
B is the end offset from the layout L1
V is the layout id for the layout used by the respective segment and is either of L11, L12 or L13 as applicable.

Subcomponent Data Structures

See Layout DB Internals for internal data structures.

Subcomponent Subroutines

See Layout DB Internals for internal subroutines.

State Specification

This module does follow state machine ind of a design. Hence, this section is not applicable.

Threading and Concurrency Model

See Layout Threading and Concurrency Model.

NUMA optimizations

Conformance

I.LAYOUT.SCHEMA.Layid: Layout identifiers are unique globally in the system, and persistent in the life cycle. It is assumed that the layout identifiers are assigned by the Layout module and Layout DB module helps to store those persistently.
I.LAYOUT.SCHEMA.Types: There are multiple layout types for different purposes: SNS, block map, local raid, de-dup, encryption, compression, etc.
Layout DB module supports storing all kinds of layout types supported currently by the layout module viz. PDCLUST and COMPOSITE. The framework supports to add other layout types, as required in the future.
I.LAYOUT.SCHEMA.Formulae:
- Parameters:
  - In case of PDCLUST layout type using LINEAR enumeration, linear formula is stored by the Layout DB and substituting parameters in the stored formula derives the real mapping information that is the list of COB identifiers.
- Garbage Collection:
  - A layout with 0 user count can stay in the DB unless it is deleted explicitly from the DB.
  - An in-memory layout is deleted when its last reference is released explicitly.
I.LAYOUT.SCHEMA.Sub-Layouts: COMPOSITE type of layout is used to store sub-layouts.

Unit Tests

Following cases will be tested by unit tests:

Test:: 1) Registering layout types including PDCLUST amd COMPOSITE types.

Test:: 2) Unregistering layout types including PDCLUST amd COMPOSITE types.

Test:: 3) Registering each of LIST and LINEAR enum types.

Test:: 4) Unregistering each of LIST and LINEAR enum types.

Test:: 5) Encode layout with each of layout type and enum types.

Test:: 6) Decode layout with each of layout type and enum types.

Test:: 7) Adding layouts with all the possible combinations of all the layout types and enumeration types.

Test:: 8) Deleting layouts with all the possible combinations of all the layout types and enumeration types.

Test:: 9) Updating layouts with all the possible combinations of all the layout types and enumeration types.

Test:: 10) Reading a layout with all the possible combinations of all the layout types and enumeration types.

Test:: 11) Checking DB persistence by comparing a layout with the layout read from the DB, for all the possible combinations of all the layout types and enumeration types.

Test:: 12) Covering all the negative test cases.

Test:: 13) Covering all the error cases.

System Tests

System testing will include tests where multiple processes are writing to and reading from the DB at the same time.

Analysis

References

For documentation links, please refer to this file : doc/motr-design-doc-list.rst

HLD of Layout Schema
Understanding Layout Schema