uml: update README to usable examples

The current `uml` README is terribly outdated and non of the examples
work by default. Fix that and while at it convert it to Markdown.

Signed-off-by: Paul Spooren <mail@aparcar.org>

2 files changed, 51 insertions, 46 deletions

diff --git a/target/linux/uml/README b/target/linux/uml/README
deleted file mode 100644
index aa7bad91ae..0000000000
--- a/target/linux/uml/README
+++ /dev/null
@@ -1,46 +0,0 @@
-OpenWrt inside a user mode linux.  Why would we even want this many ask?
-
-There are potentially a lot of reasons, one obvious one to me, it allows
-folks to 'kick the tires' without actually flashing up any hardware.  It's
-also a great environment for porting over packages, you can get a package
-fully functional in the uclibc root environment inside a uml without actually
-disturbing your 'real router', and then rebuild for a specific target once
-it's fully tested.
-
-This is a first stab at a build that 'just works' and there will be more
-cleanup to come.  The simple directions are:-
-
-Configure for uml target
-Configure with an ext4 root file system
-build it all
-
-In your bin directory you will find a kernel and an ext4 root file system
-when it's finished.  Just run it like this:-
-
-bin/targets/uml/generic/lede-uml-vmlinux
-ubd0=bin/targets/uml/generic/openwrt-uml-ext4.img
-
-The uml will start, and eventually the serial console of the uml will be at your
-console prompt.  If you would like it in xterms, substitute con=xterm and con0=xterm.
-No networking is configured, but, it's a starting point.  The resulting file system
-has just enough free space to start kicking the tires and playing in the world of
-'embedded routers' along with all the resource restrictions that come with that
-world.  
-
-To configure networking and more, refer to the user mode linux documentation online.
-A quick start goes along this line.  install the uml-utilities packages so you have
-the uml switch in and running, then add a command param to your uml start like this
-
-eth0=daemon,00:01:01:01:01:01,unix,/<your uml switch control socket here>
-
-With that in, and uml networking actually functional (can be a challenge at times),
-you should be able to ifconfig the interface and talk to the host side, or, if you
-bridged the uml switch to your host network, you should be able to run udhcp and be
-away with networking off to the world.  Again, if you are unfamiliar with uml and
-uml networking, please read the docs and how-to stuff available on the net.  It does
-take some fiddling to get it started and working right the first time, but after that,
-it opens up a whole new world of virtual machines.
-
-
-
-http://user-mode-linux.sourceforge.net/
diff --git a/target/linux/uml/README.md b/target/linux/uml/README.md
new file mode 100644
index 0000000000..63c68db57f
--- /dev/null
+++ b/target/linux/uml/README.md
@@ -0,0 +1,51 @@
+# OpenWrt inside a user mode linux
+
+> Why would we even want this many ask?
+
+There are potentially a lot of reasons, one obvious one to me, it allows folks
+to 'kick the tires' without actually flashing up any hardware.  It's also a
+great environment for porting over packages, you can get a package fully
+functional in the uclibc root environment inside a uml without actually
+disturbing your 'real router', and then rebuild for a specific target once it's
+fully tested.
+
+This is a first stab at a build that 'just works' and there will be more
+cleanup to come.  The simple directions are:-
+
+* Configure for uml target
+* Configure with an ext4 or squashfs root file system
+* Build it all
+
+In your bin directory you will find a Kernel and an root file system when it's
+finished. Just run it like this:-
+
+```shell
+./openwrt-uml-vmlinux ubd0=openwrt-uml-squashfs.img
+```
+
+The uml will start and eventually the serial console of the uml will be at your
+console prompt. If you would like it in xterms, substitute `con=xterm` and
+`con0=xterm`. **No networking is configured** but it's a starting point. The
+resulting file system has just enough free space to start kicking the tires and
+playing in the world of 'embedded routers' along with all the resource
+restrictions that come with that world.  
+
+To configure networking and more refer to the *user mode linux* documentation
+online. A quick start goes along this line. Install the `uml-utilities`
+packages so you have the `uml_switch` in and running, then add a command param
+to your uml start like this:
+
+```shell
+eth0=daemon,00:01:01:01:01:01,unix,/<your uml switch control socket here>
+```
+
+With that in, and uml networking actually functional (can be a challenge at
+times), you should be able to `ifconfig` the interface and talk to the host
+side or if you bridged the uml switch to your host network, you should be able
+to run `udhcp` and be away with networking off to the world. Again, if you are
+unfamiliar with uml and uml networking, please read the docs and how-to stuff
+available on the net. It does take some fiddling to get it started and working
+right the first time, but after that, it opens up a whole new world of virtual
+machines.
+
+http://user-mode-linux.sourceforge.net/