@Copyright 2010 (C) Cato Auestad.

Attributes to the gNewSense.org wiki and it's participants.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

gNewSense on Lemote YeeLoong
****************************

This manual is for running the gNewSense GNU/Linux operating system on Lemote YeeLoong MIPS computers with the linux-libre kernel.

Version 0.1

General information
*******************

This chapter includes general information about Lemote YeeLoong models and the gNewSense GNU/Linux operating system in the contex of the MIPS architecture.

Lemote YeeLoong
===============

As you problably already know, the Lemote YeeLoong is the first fully free laptop, running solely on free software --- even down to the BIOS level. If you are installing gNewSense on your laptop for the first time: Congratulations! There is nothing as liberating as running a completely free operating system, on completely free components.

When instructions used in this manual was written on the gNewSense wiki, it was the Lemote YeeLoong 8089 model that was used. That is the first Lemote YeeLoong model, the 8,9-inch netbook. If you own a 10-inch Lemote YeeLoong 8101 you have nothing to fear, the installation process is no different! I am writing this manual on the mentioned model and the installation went just as smooth as explained with the 8089 model.

gNewSense
=========

gNewSense is, unfortunately, one of the few GNU/Linux distrobutions of our time that is using exclusively free software in its repositories. Even the kernel has been stripped (or 'deblobbed') for all drivers and parts that are using proprietary components. The gNewSense team is working actively to have good compatability with the Lemote YeeLoong netbook specifically. Most of the packages in gNewSense repository have also been compiled for the MIPS architecture.

Compatability
=============

Be aware that there might be several compatability issues with the Lemote YeeLoong. The development of a Linux port to the YeeLoong and MIPS architecture is still pretty new, but its only going forward!

Preparing the USB drive
***********************

First of all you need to point your browser of choice to gNewSense MIPS linux image directory (http://archive.gnewsense.org/gnewsense-metad/installer/current/mipsel/loongson/netboot/) (http://archive.gnewsense.org/gnewsense-metad/installer/current/mipsel/loongson/netbook/) and download initrd.gz and vmlinux-2.6.31.6-libre1. Note that the version name on vmlinux-2.6.xx.x-libre1 may vary as the image gets updated over time.

Finished downloading? Great! Now it's time to format the USB drive in ext2 so your YeeLoong can read it. If you have already formatted the USB drive you can skip this step.

We start by running the command 'fdisk /dev/sdb' (just change it to the path of your USB drive) to erase the existing partition table. When the terminal enters fdisk and you can see 'Command (m for help):', type the letter 'p' and hit ENTER. Then type 'd', hit ENTER to delete existing partitions, and it will ask you for the number of the partition. The number is what follows 'sdb', type it in and hit ENTER. If there are more partitions, repeat the process with them. After all partitions on your USB drive have been deleted, hit 'n' and ENTER to create a new partition, then 'p' and ENTER to make it a primary partition. fdisk will now ask you which cylinder the partition should start at, just hit ENTER and fdisk will choose from the beginning of the drive by default. Then you will be asked for the last partition, again, hit enter and it will by default choose the end of the drive. You should now be back at the command prompt for fdisk. To see that everything went according to plan just hit 'p' and ENTER to see your new partition table.

Now it's time to set the filesystem type for your new partition. As mentioned above, we want to use the ext2 filesystem. Type 't' and hit ENTER and you will be asked to give the HEX-code for the filesystem you want to use. Type '83' and hit ENTER. As you have logically figured out, that is the HEX-code for the ext2 filesystem. Now just hit 'w' and ENTER to write your new partition table to your USB drive and you are all set to create your filesystem.

Back in the terminal, issue the command 'mkfs -t ext2 /dev/sdb' and as before, change 'sdb' to the path of your USB drive. Now just copy your two downloaded files onto your USB drive like usual, or with the 'cp' command.

And voila, you are set to boot gNewSense on your YeeLoong!

Booting gNewSense
*****************

There are two ways to boot up gNewSense, either by USB drive or through a network connection and TFTP. If you want to use TFTP we assume you have the technical insight necessary for us not to go into the same detail as with the USB drive.

Booting from USB drive
======================

Now that you have your USB drive ready, plug it into one of the available USB ports on your YeeLoong and hit the power button. As the YeeLoong starts, press down the <DEL>-key on your keyboard to enter the PMON command prompt. PMON is the BIOS for the YeeLoong and has a wide range of commands available do to all sorts of things we won't talk about in this manual.

If your screen is black and you have 'PMON>' in your upper left corner, you have done everything right. Type:

     load (usb0,0)/vmlinux-2.6.31.6-libre1

and hit 'ENTER' to load the linux image you copied to your USB drive. If the filename of the image you downloaded is different than the one in this manual, simply enter the correct one. Should you get an error, fear not, just type the command again and it will work.

If everything went alright, PMON should print out some weird message you don't have to think about. Now type:

     initrd (usb0,0)/initrd.gz

and hit 'ENTER' to load the initrd.gz file. Note that this might take up to 15 minutes, so go make yourself a nice cup of coffee while it's working. When it is done it too will spit out a message you don't have to think about.

This final command will initiate the gNewSense installer. Type:

     g console=tty no_auto_cmd

And you will be presented with the gNewSense installer.

Booting gNewSense from TFTP
===========================

Find your way to the gNewSense MIPS linux image directory (http://archive.gnewsense.org/gnewsense-metad/installer/current/mipsel/loongson/netboot/) (http://archive.gnewsense.org/gnewsense-metad/installer/current/mipsel/loongson/netboot/) and download the vmlinux-2.6.31.6-libre1 image and initrd.gz file and upload it to your TFTP server.

When you power up the machine, press down the <DEL>-button and you will enter PMON command prompt. Type the following to set the IP address of your YeeLoong

     ifaddr rt10 192.168.1.31

Or what ever you want the IP address to be

Then type the following to load the image from your TFTP server

     load tftp://192.168.1.31/vmlinux-2.6.31.6-libre1

To load the initrd, type the following

     initrd tftp://192.168.1.31/initrd.gz

Now, to start the installer, execute:

     g console=tty no_auto_cmd

And the gNewSense installer will appear. Continue to next step.

Starting installation of gNewSense
**********************************

The installation of gNewSense is pretty straightforward and we will not go into detail with specific steps. There are, however, a couple of things you need to know.

 1. You need an internet connection. The image you are currently running is a netboot, meaning it gets all its packages from online repositories. If you get any messages about troubles with the mirror then do not choose the option of changing mirrors, this will break the installation and you will need to start all over again.

 2. If you get a message about any issue with LVM, choose 'Continue', when later approached by a question about LVM, choose to install without (the first option).

 3. If you get a message about a issue with the partition table on the disk, just reboot and go over the process again. There is nothing dangerous about this message, the installer just didn't see the partition table changes you made earlier in the installation process.

The installer will also prompt you about the GRUB bootloader, please see the next step for further instructions about GRUB.

GRUB Bootloader
===============

The GRUB bootloader is the preferred way of booting gNewSense after installation. During the installation the gNewSense installer will ask you two questions about GRUB. First, it wants you to define a Linux command line. Type in the following line in the box

     console=tty no_auto_cmd machtype=8.9

Next the installer will ask you about the default Linux command line. The box will problably already have the value 'quiet' in it so you can just continue, but if it doesn't, make sure to write

     quiet

... in the box.

Alternative PMON2000 Bootloader
===============================

If you so choose to use the PMON2000 bootloader, this is what you need in your '/boot/boot.cfg' or '/boot.cfg' file.

     default 0
     timeout 3
     showmenu 1
     title gNewSense metad - hda1
           Kernel (wd0,0)/boot/vmlinux-2.6.27.7-libre
           initrd (wd0,0)/boot/initrd.img-2.6.27.7-libre
           args console=tty no_auto_cmd root=/dev/hda1 rootdelay=8

     title gNewSense metad - rescue via USB
           kernel (usb0,0)/boot/rescue
           args root=/dev/sda1 console=tty no_auto_cmd rootdelay=7
           #initrd (usb0,0)/boot/initrd.img

     title gNewSense metad - reinstall via USB
           kernel (usb0,0)/vmlinux-2.6.31.6-libre1
           initrd (usb0,0)/initrd.gz
           args console=tty no_auto_cmd

Running gNewSense
*****************

Everything is working? Happy to see your fully free netbook running a fully free operating system? Great!

The rest is just some additional information you might want to consider doing after installation.

Correct gNewSense metad sources in APT
======================================

To make sure you have the right sources in your sources.list in /etc/apt/-folder open up emacs and see if the file contains the following:

     deb http://archive.gnewsense.org/gnewsense-metad/gnewsense metad main
     deb-src http://archive.gnewsense.org/gnewsense-metad/gnewsense metad main

     ## gnewsense security
     deb http://archive.gnewsense.org/gnewsense-metad/gnewsense-security metad main
     deb-src http://archive.gnewsense.org/gnewsense-metad/gnewsense-security metad main

Run the newest kernel
=====================

If your installation didn't install the newest kernel (you can check this by executing the 'uname -r' command in the terminal) then you can install one easily with APT.

At the point of writing this manual, the newest libre kernel is Linux 2.6.32.9, to upgrade to this kernel, run the following command in the terminal:

     sudo apt-get install linux-image-2.6.32.9-libre-lemote

GNU Free Documentation License
******************************

GNU Free Documentation License Version 1.3, 3 November 2008

Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document ``free'' in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense.  It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does.  But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book.  We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License.  Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein.  The ``Document'', below, refers to any such manual or work.  Any member of the public is a licensee, and is addressed as ``you''.  You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A ``Secondary Section'' is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject.  (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.)  The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.  If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant.  The Document may contain zero Invariant Sections.  If the Document does not identify any Invariant Sections then there are none.

The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.  A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters.  A copying more than 1ents''.  Such a se works in the a for any