Difference between revisions of "Leapster Explorer: USB Boot"

From eLinux.org
Jump to: navigation, search
(Getting Started)
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This how-to will explain a bit about the USB booting process of the Leapfrog Explorer and provide a Linux shell script to download the file to the device.
+
== Summary ==
 +
The [[LeapPad_Explorer | LeapPad Explorer]] and [[Leapster_Explorer || Leapster Explorer]] respective bootloaders contain a feature that allows for a recovery mode, called Surgeon. When put into this mode and connected to LFConnect, it will upload and install a new firmware to your device. There are a few ways to do this yourself also.
 +
 
  
 
== Programs Needed ==
 
== Programs Needed ==
sg3_utils - Provides the needed sg_raw and sg_verify for Linux
+
sg3_utils used in a script shell/python etc
 +
* Available here [http://sg.danny.cz/sg/sg3_utils.html]
 +
* Probably included in Linux.
 +
* Windows port available at link.
  
[[File:Pager.v0.1.tgz]] shell script for Linux
+
[[LeapFrog_Pollux_Platform:_OpenLFConnect | OpenLFConnect]]
 +
* Python program that includes Windows sg3_utils or uses your Linux's built in version.
  
[[File:Pager.v0.1.zip]] command line app for Windows
 
 
Terminal app to check progress
 
  
 
== Software Needed ==
 
== Software Needed ==
 +
surgeon.cbf (found in the package)
 +
* LPAD-0x001E0011-000000.lfp
 +
* LST3-0x00170028-000000.lfp
 +
* Or you can [[Leapster_Explorer:_Testing_Kernels_via_USB_Boot| Modify a Kernel for USB Boot]]
  
 +
== Hardware Needed ==
 +
For using Surgeon once booted.
  
surgeon.cbf (found in the LST3-0x00170028-000000 package) or one of your own making, see Issues And Information
+
[[LeapFrog_Pollux_Platform:_Console_Access | Console Access]]
  
SG3-utils needs to be installed
 
  
== Hardware ==
+
== Getting Started ==
 +
If you choose to use OpenLFConnect refer to it's section [[LeapFrog_Pollux_Platform:_OpenLFConnect#USB_Booting | OpenLFConnect USB Booting]]
  
DJHI or other means of gaining a UART Console (optional)
+
You will need to connect your device through a USB cable to your host PC. Also have your Surgeon.cbf or custom file ready. Note any file you send will need to conform to the [[LeapFrog_Pollux_Platform:_File_Format_CBF | CBF File Format]].
  
== On Explorer ==
+
''' Starting USB Boot Mode '''
  
To turn on USB Boot mode, with the USB connected hold down the Right and Left Shoulder buttons along with the ? mark button, while holding them down, turn the power on, you should end up seeing a screen showing the LX connected to a PC.
+
''' Explorer ''' Hold down both shoulder buttons, and the ? button, before turning the device on.
  
== Under Linux ==
+
''' LeapPad ''' Unknown how to start with button presses at this time.
  
Download the Pager script and save it in a directory, make sure it is set to execute file permissions for your user. From a terminal run
+
Once in USB Boot mode the device is ready to accept your file. You'll need a script or program of some sort, please refer to the next section on the mechanics of the process.
  
  $ sudo ./pager.sh <filename>
+
== Scripting for USB Boot Mode ==
  
Where file name is the name of the firmware you want to download to the Explorer. In your terminal window you ran the script in, you should see something like this.
+
You'll need sg_raw and sg_verify from the sg3_utils package. You will also need to find the device id, this is done by running the sg_scan program in terminal, on windows with no options or for Linux run sg_scan -i.
  
  1: Writing bytes:0 -> 16383 to /dev/sdc
+
This will give you a list of generic scsi devices on the system, if your device is connected correctly and in USB Boot Mode, you should see a line that includes LeapFrog in it. This listing will contain the device name.
  SCSI Status: Good
+
  2: Writing bytes:16384 -> 32767 to /dev/sdc
+
  SCSI Status: Good
+
  ...
+
  ...
+
  430: Writing bytes:7045120 -> 7061503 to /dev/sdc
+
  SCSI Status: Good
+
  431: Writing bytes:7061504 -> 7077887 to /dev/sdc
+
  Verifying /dev/sdc
+
  
and it will be done.  You can check in your UART terminal, and you should see it uncompressing Linux. And you should notice, the Explorer USB Device has now changed from a Mass Storage Driver to a Network Device.
+
''' Windows '''
  
== Under Windows ==
+
We want the Physical Drive number here, you should see something on the LeapFrog line such as PD1, or PD2, depending on the number of attached drives on your system.
  
Download the Pager app and extract it, cd to the directory you put it in, from the command prompt.
+
''' Linux '''
  
  C:\>pager.exe -f <file name>
+
Here we want the /dev file. The line directly above should include /dev/sg2 or /dev/sg3 depending on your system configuration.
  
Where file name is the file you wish to download to the Explorer. You should see some info on the screen about your Explorer along with the \PhysicalDrive it is. You'll see ''Sending Packet:'' then ''Finished!'' if all went well. If you get a complaint about Explorer not found, try replugging the USB cable, or if you have more than 10 drives hooked to your host, you'll need to compile your own or unplug a few drives, as it only searches the first 10 drives. Also, this has only been tested on XP SP3 Pro.
+
''' Sending Data '''
  
== Using Surgeon ==
+
With this information in hand, you can now run a loop to grab and send the file data. This should be possible in most any language, so I'll just get the particulars across.
  
Mounting stock Explorer / and /LF/Bulk
 
  
Once surgeon.cbf has been booted, you can use the serial console as normal.
+
CBF_PACKET_SIZE = 16384
  ./etc/init.d/recovery-mounts start
+
* This is set by the bootloader, and is the size of data it expect on each pass.
you will find /patient-bulk and /patient-rfs in / which will contain their respective folders and files from the Explorer. You can then do what you need to do with them.
+
  
 +
byte1 = '00'
 +
* This will be the LSB of the LBA, it needs to be changed to 01 after the first pass, after that, doesn't matter.
  
Creating your own usb boot image
+
file_position
 +
* Keeps track of where we are in the file, while looping through the data.
  
In the source code, there is a script called make_cbf.py, this will create a cbf file out of your kernel image, it will also format the file with all the needed parameters to be used with usb boot, magic number and packet size.
+
Data Send Loop
 +
* sg_raw is provided a file to take data from
 +
* the loop will control where and how much
 +
 +
sg_raw /dev/sg2 -b -s CBF_PACKET_SIZE -n -k file_position -i "path/to/surgeon.cbf" 2A 00 00 00 00 byte1 00 00 20 00
  
== Issues And Information ==
+
This is a SCSI Write(10) command 0x2A that will send 16384 bytes of data, from file surgeon.cbf starting at file_position.
  
There are a few restrictions known at this moment.
+
You should receive a "Status:Good" after each send, if not, there is an issue.
  
Magic Number:
+
Once all the data has been sent the verify command is sent, which seems to tell the bootloader EOF on the send. The device should start booting Surgeon after this if all went well.
  
- "cbf_validate_header: magic wrong: <hex number>" shows up in the UART Console when downloading.
+
Verify
 +
* sg_verify /dev/sg2
  
The downloader on the Explorer does a few checks, CRC and the Magic Number, which is 0x9abcdef0. This must be the first 4 bytes of data the Explorer receives when downloading. So any file you send it, but have those 4 bytes in that order, first thing, if that is a problem, it should be possible to create a magic file, with just those four bytes, then modify the Pager script to work with it. The Explorer only checks for the magic number if the SCSI write(10) being sent to it, has the LBA address of 0x000000, which requires all subsequent writes to be addressed to a different LBA. In pager.sh you can see after the first packet, the LBA is switched to 0x01 for the rest of the transfer.
 
  
File Size:
+
== Using Surgeon ==
  
In the source code, there is reference to an 8mb limit, I can't verify why, but I would imagine it has something to do with the available space on the device itself, your mileage may very.
+
Mounting stock Explorer / and /LF/Bulk
 
+
CBF file format "Common Boot Format":
+
  
Not much info on this, there is a build script in the sources in /scripts that looks to build the necessary image along with all the needed data.
+
Once surgeon.cbf has been booted, you can use the serial console as normal. This script mounts /patient-bulk and /patient-rfs which are the device's normal partitions. This can be used to edit files, or fix problems with out conflicting with the OS as they are not ever in use in this state.
  
FTP:
+
./etc/init.d/recovery-mounts start
  
With surgeon.cbf successfully downloaded Explorer out puts this ''Emerald Base DFTP: Initialize DFTP'' from what I can tell, at this stage in the Surgeon/Patient recovery process the Explorer is now looking to do some FTP transfers of the /Firmware-Base images. During this process LFConnect unpacks the necessary packages to C:\Documents And Settings\<USER>\Temp\Leapfrog and they get transfered over.
+
[[Category:Leapster Explorer]]
 +
[[Category:LeapPad Explorer]]

Latest revision as of 00:00, 4 February 2012

Summary

The LeapPad Explorer and | Leapster Explorer respective bootloaders contain a feature that allows for a recovery mode, called Surgeon. When put into this mode and connected to LFConnect, it will upload and install a new firmware to your device. There are a few ways to do this yourself also.


Programs Needed

sg3_utils used in a script shell/python etc

  • Available here [1]
  • Probably included in Linux.
  • Windows port available at link.

OpenLFConnect

  • Python program that includes Windows sg3_utils or uses your Linux's built in version.


Software Needed

surgeon.cbf (found in the package)

Hardware Needed

For using Surgeon once booted.

Console Access


Getting Started

If you choose to use OpenLFConnect refer to it's section OpenLFConnect USB Booting

You will need to connect your device through a USB cable to your host PC. Also have your Surgeon.cbf or custom file ready. Note any file you send will need to conform to the CBF File Format.

Starting USB Boot Mode

Explorer Hold down both shoulder buttons, and the ? button, before turning the device on.

LeapPad Unknown how to start with button presses at this time.

Once in USB Boot mode the device is ready to accept your file. You'll need a script or program of some sort, please refer to the next section on the mechanics of the process.

Scripting for USB Boot Mode

You'll need sg_raw and sg_verify from the sg3_utils package. You will also need to find the device id, this is done by running the sg_scan program in terminal, on windows with no options or for Linux run sg_scan -i.

This will give you a list of generic scsi devices on the system, if your device is connected correctly and in USB Boot Mode, you should see a line that includes LeapFrog in it. This listing will contain the device name.

Windows

We want the Physical Drive number here, you should see something on the LeapFrog line such as PD1, or PD2, depending on the number of attached drives on your system.

Linux

Here we want the /dev file. The line directly above should include /dev/sg2 or /dev/sg3 depending on your system configuration.

Sending Data

With this information in hand, you can now run a loop to grab and send the file data. This should be possible in most any language, so I'll just get the particulars across.


CBF_PACKET_SIZE = 16384

* This is set by the bootloader, and is the size of data it expect on each pass.

byte1 = '00'

  • This will be the LSB of the LBA, it needs to be changed to 01 after the first pass, after that, doesn't matter.

file_position

  • Keeps track of where we are in the file, while looping through the data.

Data Send Loop

  • sg_raw is provided a file to take data from
  • the loop will control where and how much

sg_raw /dev/sg2 -b -s CBF_PACKET_SIZE -n -k file_position -i "path/to/surgeon.cbf" 2A 00 00 00 00 byte1 00 00 20 00

This is a SCSI Write(10) command 0x2A that will send 16384 bytes of data, from file surgeon.cbf starting at file_position.

You should receive a "Status:Good" after each send, if not, there is an issue.

Once all the data has been sent the verify command is sent, which seems to tell the bootloader EOF on the send. The device should start booting Surgeon after this if all went well.

Verify

  • sg_verify /dev/sg2


Using Surgeon

Mounting stock Explorer / and /LF/Bulk

Once surgeon.cbf has been booted, you can use the serial console as normal. This script mounts /patient-bulk and /patient-rfs which are the device's normal partitions. This can be used to edit files, or fix problems with out conflicting with the OS as they are not ever in use in this state.

./etc/init.d/recovery-mounts start