 NVRAM-WakeUp

 (C) 2001-2004, Sergei Haller <Sergei.Haller@math.uni-giessen.de>
 (C) 2002, Bernhard Rosenkraenzer <bero@arklinux.org>

 $Id: README.mb 926 2010-01-24 11:53:49Z tiber $




THIS DOCUMENT SHOULD HELP YOU TO CHOOSE THE RIGHT MOTHERBOARD SETTINGS.


First of all, you should look into boards.yaml. Maybe your board
is already there.

If not, you should look on the MB tracker list 
    http://sourceforge.net/tracker/?group_id=35022&atid=412959
or the latest SVN revision of the file boards.yaml
     http://nvram-wakeup.svn.sourceforge.net/viewvc/nvram-wakeup/trunk/nvram-wakeup/boards/boards.yaml


If you still didn't find your motherboard, you should determine, on which 
addresses the wake up date and time are stored in the NVRAM.




There are (at least) three ways to do so:

  0. how to dump the contents of NVRAM
  1. `guess-helper' script.
  2. running `guess' manually
  3. hardcore bit reading.

The three ways will be discussed in detail below.

You may also look at
   http://home.t-online.de/home/hubertus.sandmann/vdr_wakeup.htm 
you  will  find a nice detailed German introduction into nvram-wakeup,
especially how to add your own motherboard.

----------------------------------------------------------------------
      And please don't forget to send me your new configuration
            (including the output of the biosinfo program)
       it will be included in the next release of nvram-wakeup
----------------------------------------------------------------------

After  determining all the  addresses, please look at README.reboot on
the "REBOOT" problem(s).

0. how to dump the contents of NVRAM
   ---------------------------------
   If  you  are  going to use procedure 1 below, you most likely don't
   want to read this. Continue at procedure 1 below.
   
   If  you  want  to use the /dev/nvram device, you must first install
   the  nvram driver  in  your kernel. Then you can dump it's contents 
   simply by using `cat':
      cat /dev/nvram >/some/file
   
   If you want to use the direct I/O operations, then you can dump the
   contents  of  NVRAM by using  the  program `cat_nvram' shipped with 
   nvram-wakeup:
      cat_nvram >/some/file
   
   If  you  want  (or even have to) read the upper 128 bytes of NVRAM,
   then you *must* use `cat_nvram' and you must pass one option to it.
   The  accepted options are the values possible for the configuration
   option   upper_method   (see   `man   nvram-wakeup.conf'  for  more 
   information and a list of possible values). E.g.:
      cat_nvram INTEL >/some/file
   
   In  either  cases, if you need a hexdump, you can pipe the contents
   of NVRAM  through xxd   (xxd is shipped with vim, see www.vim.org.)
   or a different program:
      cat /dev/nvram      | xxd >/some/file
      cat_nvram [options] | xxd >/some/file

1. `guess-helper' script
   ------------------------
   Run  the  script  `guess-helper'.  It  will  guide  you through the
   procedure  of  creating  the files needed for the guess program and 
   eventually will run `guess' at the end.

   The output will be a configuration file which might even work ;-)

   And don't change any other BIOS settings you are not told to change
   until the procedure is finished.


2. running `guess' manually
   ------------------------
   Before starting this procedure you must have read the step 0 above.

   Don't  change  any  other  BIOS settings you are not told to change
   during the following procedure. This includes the year setting, if
   available - it's not supported by nvram-wakeup, so leave it alone.

   Create a new directory, say /var/tmp/nvram.test:

      mkdir /var/tmp/nvram.test

   (NOTE that most boards do not have a month field, so you don't need
   to enter it in that case)

   Go into your BIOS and set "Wake UP on RTC" feature to ENABLED.
   Set the day to 31, month to 12 and time to 23:59:59.
   Boot Linux.
   Dump the contents of nvram into a file:
   
      cat_nvram [options] >/var/tmp/nvram.test/31.23.59.59+

   Go into your BIOS and leave "Wake UP on RTC" feature to ENABLED.
   Set the day to 11, month to 10 and time to 12:13:14.
   Boot Linux.
   Dump the contents of nvram into a file:
   
      cat_nvram [options] >/var/tmp/nvram.test/11.12.13.14+

   Go into your BIOS and leave "Wake UP on RTC" feature to ENABLED.
   Set the day to 01, month to 01 and time to 00:00:00.
   Boot Linux.
   Dump the contents of nvram into a file:
 
      cat_nvram [options] >/var/tmp/nvram.test/01.00.00.00+

   Go into your BIOS and set "Wake UP on RTC" feature to DISABLED.
   Leave the day at 01, month to 01 and time at 00:00:00.
   Boot Linux.
   Dump the contents of nvram into a file:
 
      cat_nvram [options] >/var/tmp/nvram.test/01.00.00.00-

   Run the `guess' program in this directory:
      cd /var/tmp/nvram.test
      guess

   Its output will look like this:

      Opened file 31.23.59.59+ readonly...
      Opened file 11.12.13.14+ readonly...
      Opened file 01.00.00.00+ readonly...
      Opened file 01.00.00.00- readonly...
      Couldn't read byte 0x72 from 31.23.59.59+
      Assuming size of files 114 bytes

      ################################################
      ##  Mainboard autodetection information:
      ##
      ##    - Mainboard vendor:   "SomeManufacturer"
      ##    - Mainboard type:     "MB-123-Super Pro"
      ##    - Mainboard revision: ""
      ##    - BIOS vendor:        "My BIOS vendor"
      ##    - BIOS version:       "3.1415926"
      ##    - BIOS release:       "01.01.1999"

          checking 0x46: 0x0A 0x0A 0x0A 0x02
      addr_stat        = 0x46
      shift_stat       = 3
          checking 0x48: 0x1F 0x0B 0x01 0x01
      addr_day         = 0x48
          checking 0x49: 0x17 0x0C 0x00 0x00
      addr_hour        = 0x49
          checking 0x4A: 0x3B 0x0D 0x00 0x00
      addr_min         = 0x4A
          checking 0x6E: 0xC5 0x78 0x55 0x4D
      addr_chk_h       = 0x6D   # guessed
      addr_chk_l       = 0x6E


   You can redirect stdout into a file:
      guess | cat > mymb.conf
 
      Opened file 31.23.59.59+ readonly...
      Opened file 11.12.13.14+ readonly...
      Opened file 01.00.00.00+ readonly...
      Opened file 01.00.00.00- readonly...
      Couldn't read byte 0x72 from 31.23.59.59+
      Assuming size of files 114 bytes
          checking 0x46: 0x0A 0x0A 0x0A 0x02
          checking 0x48: 0x1F 0x0B 0x01 0x01
          checking 0x49: 0x17 0x0C 0x00 0x00
          checking 0x4A: 0x3B 0x0D 0x00 0x00
          checking 0x6E: 0xC5 0x78 0x55 0x4D
 
   Now the file mymb.conf will contain the settings:

      ################################################
      ##  Mainboard autodetection information:
      ##
      ##    - Mainboard vendor:   "SomeManufacturer"
      ##    - Mainboard type:     "MB-123-Super Pro"
      ##    - Mainboard revision: ""
      ##    - BIOS vendor:        "My BIOS vendor"
      ##    - BIOS version:       "3.1415926"
      ##    - BIOS release:       "01.01.1999"

      addr_stat        = 0x46
      shift_stat       = 3
      addr_day         = 0x48
      addr_hour        = 0x49
      addr_min         = 0x4A
      addr_chk_h       = 0x6D   # guessed
      addr_chk_l       = 0x6E


   rtc_sec, rtc_min and rtc_hour are just for your information,
   and are currently not used by nvram-wakeup. You must
   remove these lines or you will get an syntax error.

   If  your  nvram  has  a size of 128 bytes or more and you get these
   three lines (they should appear only together):
      rtc_sec  = 0x73
      rtc_min  = 0x75
      rtc_hour = 0x77
   then you have to replace them by
      rtc_time = ON

   (I should do this automatically in one of the next versions)

   ALL VALUES  calculated  by `guess' are given  WITHOUT ANY WARRANTY.
   You should try

      nvram-wakeup --configfile=mymb.conf -s xxxx --nowrite

   and double check all values.

   If  there  is  something  strange in the output, please send me the
   whole  (I repeat:  WHOLE)  output  of `guess'. First, I will try to 
   calculate the right values for your board and second, to fix `guess' 
   to calculate them right.

3. hardcore bit reading
   --------------------
   If  you want to know what's really going on there or if you're just
   bored ;^), try this method.

   Before starting this procedure you must have read the step 0 above.

   Here is a simple step-by-step instruction how to do so by hand:
   
    - enable the wake up time in the BIOS
    - hexdump the contents of NVRAM into a text file.
    - go again to your BIOS and change only the wakeup day.
    - hexdump the contents of NVRAM and see which bytes changed (there
      should be two or three of them: the one is the day  byte and the
      other is/are the checksum byte(s).
    - go again to your BIOS and change only the wakeup hour.
    - hexdump the contents of NVRAM and see which bytes changed (there
      should  be  again two or three of them: the one is the hour byte 
      and the other is/are the checksum byte(s).
    - do  the  same  for the minute and the second (and month, if your
      BIOS has such a feature).
    - disable the wakeup in the BIOS.
    - dump the contents of NVRAM and see which bytes changed now. (one
      bit should be changed in some byte)
 
   While  doing  this look at the values of the date/time bytes closly
   and  notice at which bits they are stored, i.e. if the value of the 
   day  is 15 and byte is  0x0F = 00001111 
                                     ^^^^^ 01111 = 15
                 or it is  0x4F = 01001111
                                     ^^^^^ 01111 = 15
   then shift_day is 0
             but if it is  0x1E = 00011110
                                    ^^^^^  01111 = 15
   then shift_day is 1.

   Some  boards  use  the BCD notation, e.g. they store 15 as 0x15. In
   this case, shift_day is 0.

   Especially try the extreme values to determine both checksum bytes:
   day 01, time 00:00:00 and day 31, time 23:59:59.
   
   If  you  still  have  only one checksum byte (say at address 0x31),
   then  it is the second byte (the lower 8 bits). The first one (with 
   upper  8  bits) is most likely the one just before (in this case at 
   address  0x30).  You have to write down the addresses of both bytes 
   (in this case 0x30 and 0x31).

   Now  you  are done. You have to put all these values (addresses and 
   shifts  of  the  bytes) into a text file of your choice (usually in
   /etc/nvram-wakeup.conf). 

   Read  `man nvram-wakeup.conf'  for more information on the possible
   configuration options for the file.


