[PATCH 2/5] Documentation: highlight questions in the FAQ

[Claudio Scordino]

This commit highlights questions (using the bold character) to ease
reading of the FAQ.

Signed-off-by: Claudio Scordino <cla...@evidence.eu.com>
---
FAQ.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/FAQ.md b/FAQ.md
index 33075ed..dcc5fbd 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -4,7 +4,7 @@ FREQUENTLY ASKED QUESTIONS
General
-------

-Q: Linux already has KVM. Why do I need another hypervisor?
+**Q: Linux already has KVM. Why do I need another hypervisor?**

A: Short answer: in most cases, you don't. There are many hypervisors available
in Linux: KVM, Xen, Oracle VM VirtualBox, to name a few. Most of them are
@@ -25,8 +25,8 @@ platform for mixing critical applications in functional safety scenarios.
It can also fulfill secure isolation requirements, although this was not the
focus so far.

-Q: Jailhouse is Asymmetric Multiprocessing (AMP). This means it will be slow due
-to CPU cache thrashing.
+**Q: Jailhouse is Asymmetric Multiprocessing (AMP). This means it will be slow due
+to CPU cache thrashing.**

A: These concerns do have grounds. However, what is "slow" is determined by
Service Level Agreement (SLA), and we hope the effect will be negligible in the
@@ -41,8 +41,8 @@ always comes at price.
Debugging
---------

-Q: When I enable Jailhouse or run an inmate, my machine hangs. How do I know
-what's going on? Can I use dmesg, ftrace or similar tool?
+**Q: When I enable Jailhouse or run an inmate, my machine hangs. How do I know
+what's going on? Can I use dmesg, ftrace or similar tool?**

A: No. Jailhouse runs at the level lower than the Linux kernel, and if something
goes wrong, there are no guarantees that Linux can continue executing. Instead,
--
2.7.4

[Claudio Scordino]

This commit adds further information in the FAQ about how to enable
error tracing on serial console.

Signed-off-by: Claudio Scordino <cla...@evidence.eu.com>
---

FAQ.md | 3 +++
1 file changed, 3 insertions(+)

diff --git a/FAQ.md b/FAQ.md
index dcc5fbd..5d2cc05 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -57,6 +57,9 @@ If everything else fails, consider buying a PCI serial adapter. Now, attach
a Linux machine to the other side of serial connection and use terminal emulator
like minicom to grab the log messages.

+To enable error tracing, put ```#define CONFIG_TRACE_ERROR``` in file
+hypervisor/include/jailhouse/config.h before compiling.
+
Please note Jailhouse developers may ask you for these logs, shall you come for
help to jailhouse-dev mailing list, because they are extremely useful to analyze
machine hangs. So please have the logs at hand, if possible.
--
2.7.4

[Claudio Scordino]

This commit explains that on GRUB2 three characters are needed for
escaping the dollar sign in the memmap boot argument.

See thread discussion at
https://groups.google.com/forum/#!topic/jailhouse-dev/uRYWRdbIdOg

Signed-off-by: Claudio Scordino <cla...@evidence.eu.com>
---

README.md | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6c8e677..93c1bde 100644
--- a/README.md
+++ b/README.md
@@ -216,12 +216,16 @@ need to add

memmap=66M$0x3b000000

-as parameter to the command line of the virtual machine's kernel. The Jailhouse
-QEMU cell config will block use of the serial port by the guest OS, so make
-sure that the guest kernel command line does NOT have its console set to log
-to the serial port (ie remove any 'console=ttyS0' arguments from the grub
-config). Reboot the guest and load jailhouse.ko. Then enable Jailhouse like
-this:
+as parameter to the command line of the virtual machine's kernel. Note that if
+you plan to put this parameter in GRUB2 variables, then you will need three
+escape characters before the dollar
+(e.g. ```GRUB_CMDLINE_LINUX_DEFAULT="memmap=66M\\\$0x3b000000"```).
+
+The Jailhouse QEMU cell config will block use of the serial port by the guest
+OS, so make sure that the guest kernel command line does NOT have its console
+set to log to the serial port (ie remove any 'console=ttyS0' arguments from the
+grub config). Reboot the guest and load jailhouse.ko. Then enable Jailhouse
+like this:

jailhouse enable /path/to/qemu-vm.cell

--
2.7.4

[Claudio Scordino]

This commit replaces the wrong (i.e. not working) URL for the
mailing list's archives with a working one.

Signed-off-by: Claudio Scordino <cla...@evidence.eu.com>
---

README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 316ed01..b513774 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ Mailing list:
- https://groups.google.com/forum/#!forum/jailhouse-dev/join

- Archives
- - http://news.gmane.org/gmane.linux.jailhouse
+ - https://groups.google.com/forum/#!forum/jailhouse-dev

Continuous integration:

--
2.7.4

[Claudio Scordino]

This commit explains that the AMD target under QEMU/KVM is not yet fully
supported by Jailhouse. It is therefore better to use Intel when running
under QEMU/KVM.

See thread discussion at
https://groups.google.com/forum/#!topic/jailhouse-dev/W3g-70EahXc

Signed-off-by: Claudio Scordino <cla...@evidence.eu.com>
---

README.md | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index b513774..6c8e677 100644
--- a/README.md
+++ b/README.md
@@ -178,9 +178,10 @@ Demonstration in QEMU/KVM
-------------------------

The included system configuration qemu-vm.c can be used to run Jailhouse in
-QEMU/KVM virtual machine on x86 hosts (Intel and AMD are supported). Currently
-it requires Linux 4.4 or newer on the host side. QEMU version 2.7 or newer is
-required.
+QEMU/KVM virtual machine on x86 hosts. Currently it requires Linux 4.4 or
+newer on the host side. QEMU version 2.7 or newer is required. Better using an
+Intel architecture since Jailhouse does not yet fully support AMD under
+QEMU/KVM.

You also need a Linux guest image with a recent kernel (tested with >= 3.9) and
the ability to build a module for this kernel. Further steps depend on the type
--
2.7.4

[Jan Kiszka]

I'll leave the gmane link (but only after google groups) because the is
hope it will eventually recover.

Jan

--
Siemens AG, Corporate Technology, CT RDA ITP SES-DE
Corporate Competence Center Embedded Linux

[Jan Kiszka]

On 2016-09-19 12:10, Claudio Scordino wrote:

In fact, we should also split qemu-vm.c into qemu-vm-{intel,amd}.c and
remove the iommu configuration from the latter. Later on, when the AMD
IOMMU emulation is fully merged and functional in QEMU, we can move in
corresponding settings into that file. For now, it would allow using
Jailhouse on an AMD host, provided one doesn't run into the KVM issue
(less likely when there is a 1:1 relationship between virtual and
physical cores).

[Jan Kiszka]

On 2016-09-19 12:10, Claudio Scordino wrote:

IIRC, you need this when adding the line to /etc/default/grub. That's
the common case, yes, but better make it clear.

> +The Jailhouse QEMU cell config will block use of the serial port by the guest
> +OS, so make sure that the guest kernel command line does NOT have its console
> +set to log to the serial port (ie remove any 'console=ttyS0' arguments from the
> +grub config). Reboot the guest and load jailhouse.ko. Then enable Jailhouse
> +like this:
>
> jailhouse enable /path/to/qemu-vm.cell
>
>

Thanks,