Skip to content
This repository has been archived by the owner on May 12, 2021. It is now read-only.

Create an architecture document #1

Closed
jodh-intel opened this issue Dec 21, 2017 · 2 comments
Closed

Create an architecture document #1

jodh-intel opened this issue Dec 21, 2017 · 2 comments
Labels
high-priority Very urgent issue (resolve quickly)

Comments

@jodh-intel
Copy link
Contributor

We need to create an ARCHITECTURE.md that covers the overall system.

This document could, if necessary, reference architecture documents found in each components repository. These would essentially document just themselves. The intent is to define once and reference as many times as needed.

For example, the ARCHITECTURE.md created in this repository may say something like:

For further details on the Kata shim implementation, refer to the shim architecture document

Component repositories

The individual README.md files in each code repository must contain a reference to this central architecture document.

If a component repository has a separate ARCHITECTURE.md this:

  • Must be referenced in the components README.md.
  • Must itself reference the central ARCHITECTURE.md document.

For an example of what we should be aiming for, see the Clear Containers architecture document:

Diagrams

All diagrams must:

  • Be stored along with their corresponding "source" files (for example, if a .png file is referenced, the .svg file that was used to generate the .png must also be stored to allow the diagrams to be updated by all.
  • Use freely available open formats for their sources.
@grahamwhaley
Copy link
Contributor

@jodh-intel
Copy link
Contributor Author

Technically, no, as we're missing the sources for the PNG files.

@egernst - could you rustle up the sources for the PNG files here: https://github.com/kata-containers/documentation/tree/master/arch-images ?

@jodh-intel jodh-intel removed the backlog label Jun 4, 2019
@egernst egernst closed this as completed Jul 17, 2019
devimc pushed a commit to devimc/kata-documentation that referenced this issue Sep 2, 2019
devimc pushed a commit to devimc/kata-documentation that referenced this issue Sep 2, 2019
Re-implement image builder script to generate an image with a double MBR +
a DAX metadata. The DAX metadata is read by the NVDIMM driver to know the
beginning of the data in the pmem device.
This new image format is required to enable DAX in the kernels and hypervisors
that support NVDIMM, without breaking the compatibility with the kernels and
hypervisors that don't support it.

Following diagram shows how the resulting image will look like

```
	.-----------.----------.---------------.-----------.
	| 0 - 512 B | 4 - 8 Kb |  2M - 2M+512B |    3M     |
	|-----------+----------+---------------+-----------+
	|   MBR kata-containers#1  |   DAX    |    MBR kata-containers#2     |  Rootfs   |
	'-----------'----------'---------------'-----------+
	      |          |      ^      |        ^
	      |          '-data-'      '--------'
	      |                                 |
	      '--------rootfs-partition---------'
```

MBR: Master boot record.
DAX: Metadata required by the NVDIMM driver to enable DAX in the guest [1][2]
(struct nd_pfn_sb).
Rootfs: partition that contains the root filesystem (/usr, /bin, etc).

Kernels and hypervisors that support DAX/NVDIMM read the MBR kata-containers#2,
otherwise MBR kata-containers#1 is read.

[1] - https://github.com/kata-containers/osbuilder/blob/master/image-builder/\
nsdax.gpl.c
[2] - https://github.com/torvalds/linux/blob/master/drivers/nvdimm/pfn.h

fixes kata-containers#263

Signed-off-by: Julio Montes <julio.montes@intel.com>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
high-priority Very urgent issue (resolve quickly)
Projects
None yet
Development

No branches or pull requests

3 participants