README.TXT 07/16/2008 ----------------------------------------- VERSALOGIC DEBIAN LiveCD - DEV-CD-L6-1.00 ----------------------------------------- Board Name : EPM-14/EBX-11 (COUGAR/PYTHON) Kernel Version : 2.6.25-5 (Debian Sources) Debian Version : 4.0r3 (Etch/Stable) VL Debian Installer : 3.1.0 ------------- NEW FEATURES! ------------- 1. LM-SENSORS (Temperature monitoring) supported (just type "sensors" in a terminal window or on a console) 2. AMD Geode WATCHDOG support & MFGPT support (See section 8) 3. AMD Geode Hardware access utilities (See section 9) 4. Inclusion of kernel source/headers files for module compiling and driver development (See section 10) ----------------- TABLE OF CONTENTS ----------------- 1. Legal Disclaimer 2. Purpose 3. Hardware Requirements 4. Install Instructions 5. Features of the Install Types 6. What to do once the installation is finished 7. Adding new programs to your Debian Install 8. Watchdog and MFGPT 9. AMD Geode Hardware Access Utilities 10.Advanced User Package (AUP) 11.Important Notes 12.References -------------------- 1.0 LEGAL DISCLAIMER -------------------- VersaLogic is making no claims of usability, efficacy or warranty. Information in this document is provided in connection with VersaLogic(R) products. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted by this document. VersaLogic assumes no liability whatsoever, and VersaLogic disclaims any express or implied warranty relating to sale and/or use of VersaLogic(R) products, including liability or warranties relating to fitness for a particular purpose, merchantability or infringement of any patent, copyright or other intellectual property right. VersaLogic(R) products are not intended for use in life-saving or life-sustaining applications. VersaLogic Corporation disclaims all warranties and liabilities for the use of this document and the information contained herein, and assumes no responsibility for any errors which may appear in this document, nor does VersaLogic make a commitment to update the information contained herein. VersaLogic reserves the right to make changes to this document at any time, without notice. Copyright (c) VersaLogic Corporation, 2008 Install script source code inquiries should be directed to support@versalogic.com ----------- 2.0 PURPOSE ----------- Installing Debian can be a difficult and time consuming effort, even when using the latest installer guide added with the release of "Etch". Our goals were to make installing the Debian OS installation as painless as possible for our customers, provide multiple installation images that balance footprint versus functionality in different ways and to pre-configure any product specific support such as video, cardbus, etc. This also constitutes the difference between our installation and the Debian "Etch" CD/DVD installation. ------------------------- 3.0 HARDWARE REQUIREMENTS ------------------------- 1.(a) USB Mouse & Keyboard (For EPM-14) (b) PS2/USB Mouse & Keyboard (For EBX-11) 2. IDE(PATA)/USB CD-ROM or DVD-ROM 3. An IDE Device (Hard Disk Drive or Compact Flash) on which the system will be installed 4. Minimum 256MB RAM 5. CRT/FPD Monitor ------------------------ 4.0 INSTALL INSTRUCTIONS ------------------------ 1. The installer is placed on the desktop and is labeled "VersaLogic Debian Installer". Just double click the icon and the installation wizard will start. 2. You will be given choice of the IDE device on which you would like to install. You can install on Hard Disk Drives and Compact-Flash Drives i.e. any read-write IDE device. 3. The installer will take you step-by-step through the installation process. You can select one of three types of install (minimum, medium and full.) a) Minimal Install: This is essentially a console-based installation with minimum functionality. It does not have any graphical features. b) Medium Install: This has everything that Minimal Install does plus it has Xorg installed which is a Graphical Server (called X Server). This will provide you limited graphical features through the window manager 'fluxbox'. It should launch automatically once you log into the system. c) Full Install: This has everything mentioned above (except fluxbox) plus it has a Graphical User Environment, GNOME. This is the expandable, full distribution environment. 4. During the installation if any unexpected error occurs, you will be notified about it and you can see the error in /tmp/errorLog.txt file by running the following command: root@debian# less /tmp/errorLog.txt After installation, the above file should be empty. In other words, an empty file indicates a successful installation. 5. You will have to run the installer as "root". --------------------------------- 5.0 FEATURES OF THE INSTALL TYPES --------------------------------- 1. Minimal Install: a) Accessing USB Devices b) Internet (LAN AND WLAN) DHCP client, FTP, TELNET c) SSH, SFTP remote connection d) System Administration, PCIUTILS e) PC-CARD BUS f) LCD and CRT Support 2. Medium Install: All above (a-f) plus the following: g) Xorg(X server installed) + Fluxbox(Window Manager) h) Graphical Based Login(xdm) i) Sound k) Graphical web browser l) Limited Graphic capability 3. Full Install: All above (a-i) plus the following: m) GNOME GUI n) Can perform some administrative tasks using GUI ------------------------------------------------- 6.0 WHAT TO DO ONCE THE INSTALLATION IS FINISHED? ------------------------------------------------- 1. Reboot your system once the installation process succeeds. 2. Press 'Delete' key on the keyboard to go to the CMOS setting. Choose Basic CMOS Settings. 3. Under the DRIVE ASSIGNMENT ORDER section (on the left hand side) assign your device as Drive C and under the BOOT ORDER section (middle) set Drive C as your first boot device. For example: Suppose during the installation process you want to selected hdb (Step 3 in General Instructions) as the IDE device to install the Debian system, the corresponding CMOS-BIOS settings will be: In DRIVE ASSIGNMENT ORDER section, DRIVE C: ide 1/Pri Slave In DRIVE ASSIGNMENT ORDER section, 1st BOOT: Drive C The following are the mapping for the rest of the devices: hda = ide 0/Pri Master hdb = ide 1/Pri Slave hdc = ide 2/Sec Master hdd = ide 3/Sec Slave 4. Save the CMOS setting and reboot. Please see section 11 point 7. 5. You should see the GRUB bootloader screen and it will automatically boot into your new system in a few seconds. 6. Once the system boots and presents the login screen, you will have to use the following user name and password to log into the system. To login as root user: login:root password:password The root user will be able to do all the administrative tasks. To login as regular user: login:user password:password 7. You can find the corresponding kernel headers files for the installed kernel (2.6.25-5) in the directory "/root/AUP" folder on the CD. Please see section 10. ---------------------------------------------- 7.0 ADDING NEW PROGRAMS TO YOUR DEBIAN INSTALL ---------------------------------------------- Even though we have tried to provide a good base of installed programs, it would not be practical for us to provide everything that is available to everyone. In this section, we will provide a basic tutorial on how to add new software to your installed base system. Adding additional software ------------------------- Once you have your basic installation completed, the next thing you will probably want to do is add additional software. The APT suite of programs is, by far, the easiest way to accomplish this task. APT is an acronym for Advanced Package Tool and it is essentially an automated dependency resolver and front end for the dpkg program. It will figure out what the dependencies are for a given software package and then it will manage the calls to dpkg which actually does the work of installing them. Together, apt and dpkg make installing new packages very straightforward. Example ------- Let's go through an example. You want to first make sure you are connected to the Internet--all three of our Debian installations contained on the VersaLogic Debian install CD are configured to use DHCP, by default. And, in most cases, you just need to connect an ethernet cable to your network to use it. At the console prompt, type "apt-get update" and enter. This will refresh the local package database. It's a good practice to do this step fairly often (before you are about to install new software) to make sure that the latest package information is available to APT. Once that process is finished, type "apt-get install traceroute" then enter. "traceroute" is in the name of the package we want to install, so APT will go find any packages that have that name, and often automatically decides which one is best for your system. It also determines what other packages need to be installed to make traceroute work, and it go ahead and install those as well. Installing packages from "testing" repositories i.e. other than "stable" ------------------------------------------------------------------------ By default, APT will look in /etc/apt/sources.list to determine where to download the packages from. We have set up the system to look in a "stable" online repository by default, but if it doesn't exist there, APT can also look in a "testing" repository; testing means that the package is being tested and has been stable for at least 14 days, but has not yet been added to the formal Debian stable release. This scheme strikes the best balance between system stability and package availability since unlike other Linux distributions, Debian's developers can take years to move testing packages to stable, which happens only for major releases. To enable APT to download packages from testing repository, you will have to uncomment (remove the leading "#" symbol) the following lines from /etc/apt/sources.list file: #deb http://mirrors.kernel.org/debian testing main contrib #deb-src http://mirrors.kernel.org/debian testing main contrib Additional information/links for APT package management system -------------------------------------------------------------- Debian essentially maintains 3 types of distributions 1.Stable 2.Testing 3.Unstable For more information, refer to the following web site: http://www.nl.debian.org/doc/manuals/reference/ch-system.en.html All of our 3 images with respect to the above 3 distribution stand as follow: 1.Minimal - Stable 2.Medium - Stable 3.Full - Stable For more information, refer to the following web sites: http://www.debian.org/doc/manuals/apt-howto http://jaqque.sbih.org/kplug/apt-pinning.html http://www.argon.org/~roderick/apt-pinning.html http://wiki.debian.org/AptPinning APT Configuration files ----------------------- Also, look at the following files to customize the apt-get system: /etc/apt/apt.conf /etc/apt/sources.list /etc/apt/preferences Also, please run the command #apt-get update every time you decide to install any package. This is very important to keep the local repository in sync with the Debian repository ---------------------- 8.0 WATCHDOG and MFGPT ---------------------- Watchdog (CONFIG_GEODE_WDT) support ----------------------------------- (i) Loading the driver The watchdog driver ("geodewdt") for AMD Geode machines is included in all the three images. To load the watchdog driver simply give the command: debian:~# modprobe geodewdt or you can Un-comment the line: #geodewdt like this: geodewdt in the /etc/modules file so that the driver will load automatically upon boot. (ii) Verify the loading To verify if the driver is loaded properly check the /dev/ directory for the existence of the device file "watchdog": debian:~# ls -l /dev/watchdog Also you can do a "dmesg" and check for the following similar lines: [ 24.554730] geode-mfgpt: 6 MFGPT timers available. [ 24.554748] geode-mfgpt: Registered timer 1 by giving the following command: debian:~# dmesg | grep geode-mfgpt (iii) Using the Watchdog driver To use watchdog driver, we have included the "watchdog" daemon package. You can configure the watchdog the editing the following file: /etc/watchdog.conf You can restart the watchdog daemon package by giving the following command: debian:~# /etc/init.d/watchdog restart MFGPT (CONFIG_GEODE_MFGPT_TIMER) support ---------------------------------------- (i) MFGPT support By default the CONFIG_GEODE_MFGPT_TIMER i.e. support for Multi-Function General Purpose Timer is disabled in the kernel because of an IRQ issue. For more details see the following good discussion threads: http://marc.info/?l=linux-kernel&m=120050717608600&w=2 http://lkml.org/lkml/2008/1/18/591 (ii) Enable MFGPT In order to enable the Geode's MFGPT support, you need to enable CONFIG_GEODE_MFGPT_TIMER=y in the kernel configuration file and compile it. Then you need to pass the following parameters during boot time or you can edit your /boot/grub/menu.lst file to make it permanent. For example: "mfgpt_irq=8" Basically you need to assign the MFGPTs a free IRQ. You can check the available/free IRQ in the system by giving the following command: debian:~# cat /proc/interrupts For more information on IRQs on the boards please refer to: EBX-11 Manual: http://www.versalogic.com/Products/Manuals/MEBX11.pdf EPM-14 Manual: http://www.versalogic.com/Products/Manuals/MEPM14.pdf Notes: ------ a) Try not to use IRQ 7. See the above discussion thread for further details on this. b) Furthermore the inclusion of watchdog driver is EXPERIMENTAL at this stage and it can cause unnecessary system reboots/shutdown once you load the driver. Please use the watchdog driver at your own risk. If you encounter any problems while using the driver you will need to ask the LKML (http://lkml.org/). --------------------------------------- 9.0 AMD GEODE HARDWARE ACCESS UTILITIES --------------------------------------- The folder '/root/geode_hw_utils' contains some handy utilities for reading/writing/modifying hardware register values on AMD Geode Platforms. Following is a brief description of these utilities: a) Loadreg - A command line utility which allows user to read/write any I/O, Memory, MSRs, PCI configuration space location. b) Cyreg - A menu driven utility which displays I/O, Memory, MSRs, PCI configuration space data. You can customize the display menu (hardware regions) i.e. what information to be shown, by modifying the text file 'cyreg.txt'. We have included a sample text file which includes some important hardware regions. c) GX_UTILS - A kernel module which is required by above two utilities to work correctly. You don't have to load/unload this module. The above utilities takes care of this automatically. To run these utilities do the following: debian:~# cd /root/geode_hw_utils debian:~# cyreg or debian:~# loadreg -------------------------------- 10.0 Advanced User Package (AUP) -------------------------------- If you don't want to install the VersaLogic Debian images and would like to have your own custom install (Debian or a non-Debian) then this section is for you. No matter which distro you choose you will need a kernel with all the updated hardware support. The folder "AUP" under `/root` directory contains a zip file with following contents: a) Kernel source files b) Kernel headers files c) Kernel config file d) Installable Kernel deb file (for Debian-based distros) e) A patch file for getting Watchdog and MFGPT support Note: You will not require the patch if you are using kernel version 2.6.26 or above. -------------------- 11.0 IMPORTANT NOTES -------------------- 1. All three install images are based on a VersaLogic customized Debian kernel using the Debian kernel source 2.6.25-5. 2. All the three images have custom compiled kernel specifically for this particular board. 3. For convenience, the Mozilla Web browser included in the full install is configured to start automatically at boot up. If you wish to disable this feature, follow the steps outlined below. a) Click on "Desktop" menu located on the upper menu bar b) Choose "Preferences" sub-menu c) Choose "Sessions" d) Click on the "Current Sessions" tab e) Select "mozilla" entry f) Click "Remove" button g) Close the Sessions dialog 4. For best viewing results on a normal CRT/FPD monitor, use 1024x768 resolution. For best viewing results on a LVDS Flat Panel Display, use 800x600 resolution. 5. In case if you find the boot process (the green progress bar) has stuck for more than 2-3 minutes and/or you are not able to get your console back then please disable/remove boot splash program 'splashy'. For disabling splashy you need to edit the file /etc/default/splashy and set the variable: ENABLE=0 For removing splashy completely give the following command: debian:~# dpkg --purge splashy The program "splashy" is under heavy development and has lots of bugs: http://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=splashy;dist=unstable 6. Installing on USB devices such as Flash/Jump/Thumb drives and Hard Drives is not supported yet. 7. If you are installing on EPM-14 (Cougar) board and you change IDE Primary Master/Slave settings in DRIVE ASSIGNMENT ORDER section in CMOS then make sure you power down the board completely and then power it up. If you fail to follow these steps then you might have trouble booting from your boot device. This does not happen on EBX-11 (Python) although we recommend doing the same for it. Also if you further encounter boot problems (device fails to boot) when Compact Flash (CF) is present as a "Slave" with a Hard Drive as "Master", do not declare the CF device in the DRIVE ASSIGNMENT ORDER section in CMOS. Linux will automatically detect the CF even if it is not declared in CMOS. 8. If you connect a USB device such as floppy/hard-drive/CD-ROM you should be able to access them under `/media/` directory. --------------- 12.0 REFERENCES --------------- Below is a list of books and web sites that we recommend to anyone who wants to learn more about Debian or GNU/Linux in general. 1. Debian System, Concepts and Techniques, by Martin F. Krafft, Open Source Press, 2005. 2. GNU/Linux Application Programming, by M. Tim Jones, Charles River Media, 2005. 3. www.debian.org, Debian's Official home on the Internet. 4. www.x.org, The X.Org Foundation provides an open source implementation of the X Window System. 5. Newsgroup: comp.os.linux, contains plenty of free advice.