← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to roms/u-boot/board/palmtreo680/README

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
roms/u-boot/board/palmtreo680/README
 
1
 
 
2
README for the Palm Treo 680.
 
3
 
 
4
Copyright (C) 2013 Mike Dunn <mikedunn@newsguy.com>
 
5
 
 
6
You may reproduce the contents of this file entirely or in part, but please
 
7
credit me by name if you do.  Thanks.
 
8
 
 
9
 
 
10
Intro
 
11
=====
 
12
 
 
13
Yes, you can program u-boot onto the flash of your Palm Treo 680 so that u-boot
 
14
(then Linux, Android, ...) runs at power-up.  This document describes how, and
 
15
gives some implementation details on this port of u-boot and describes how the
 
16
Treo 680 boots from reset.
 
17
 
 
18
But first, I probably don't need to tell you that after doing this, your phone
 
19
will no longer run PalmOS.  You *may* be able to later restore your phone to its
 
20
original state by creating a backup image of the flash before writing u-boot
 
21
(details below), but this is not heavily tested and should not be relied upon.
 
22
There is also the possibility that something may go wrong during the process of
 
23
programming u-boot, leaving you with a bricked phone.  If you follow these
 
24
instructions carefully this chance will be minimized, but I do not recommend
 
25
that you program u-boot onto a phone that you can not afford to lose, and
 
26
certainly not one that contains important data that is not backed up elsewhere.
 
27
I AM NOT RESPONSIBLE FOR THE LOSS OF YOUR PHONE.  DO THIS AT YOUR OWN RISK.
 
28
Having said that, feel free to send me a note cursing me out if something does
 
29
go wrong, but please tell me what happened exactly.  For that matter, I'd love
 
30
to hear from you if you succeed.
 
31
 
 
32
 
 
33
Details on the SPL
 
34
==================
 
35
 
 
36
The docg4 features a 2k region at the start of its address space that interfaces
 
37
to the system bus like a NOR flash.  This allows the docg4 to function as a boot
 
38
ROM.  The Treo 680 uses this feature.  The contents of this 2k region are
 
39
write-protected and can not be reprogrammed.  Fortunately, the code it contains
 
40
does what we need to do, at least partially.  After some essential hardware
 
41
initialization (like the SDRAM controller), it runs an IPL (initial program
 
42
loader) that copies 128K (no more, no less) from flash to a fixed address in
 
43
SDRAM (0xa1700000) and jumps to it.  128K is too small for u-boot, so we use it
 
44
to load a u-boot secondary program loader (SPL).  But since our SPL only
 
45
occupies a little over 1k, we can economize on flash usage by having the IPL
 
46
load a portion of u-boot proper as well.  We let the IPL load the first 128k of
 
47
a concatenated spl + u-boot image, and because the SPL is placed before u-boot
 
48
proper, the IPL jumps to the SPL, which copies the portion of u-boot that the
 
49
IPL has already loaded to its correct SDRAM address, and then loads the
 
50
remainder of u-boot and jumps to it.
 
51
 
 
52
 
 
53
The docg4's "reliable mode"
 
54
===========================
 
55
 
 
56
This is a special mode of operation of the docg4's integrated controller whereby
 
57
consecutive pairs of 2k regions are used in parallel (in some fashion) to store
 
58
2k of data.  In other words, the normal capacity is halved, but the data
 
59
integrity is improved.  In this mode, the data is read or written from pages in
 
60
even-numbered 2k regions (regions starting at 0x000, 0x1000, 0x2000, ...).  The
 
61
odd-numbered 2k regions (regions starting at 0x800, 0x1800, 0x2800, ...) are
 
62
transparently used in parallel.  In reliable mode, the odd-numbered 2k regions
 
63
are not meant to be read or written directly.
 
64
 
 
65
Reliable mode is used by the IPL because there is not enough space in its 2k
 
66
footprint to implement the BCH ecc algorithm.  Data that is read while reliable
 
67
mode is enabled must have been written in reliable mode, or the read fails.
 
68
However, data written in reliable mode can also be read in normal mode (just not
 
69
as reliably), but only from the even-numbered 2k regions; the odd-numbered 2k
 
70
regions appear to contain junk, and will generate ecc errors.  When the IPL and
 
71
SPL read from flash, the odd-numbered 2k regions are explicitly skipped.  The
 
72
same is true for the flash_u-boot utility when it writes the u-boot image in
 
73
reliable mode.
 
74
 
 
75
The docg4 Linux driver supports writing in reliable mode (it is enabled by the
 
76
module parameter), but not reading.  However, the u-boot docg4_spl driver does
 
77
read in reliable mode, in the same fashion as the IPL.
 
78
 
 
79
 
 
80
Details on the IPL and its data format
 
81
======================================
 
82
 
 
83
Starting from block 5 and counting upward, the IPL will search for and load the
 
84
first two blocks it finds that contain a magic number in the oob of the first
 
85
page of the block.  The contents are loaded to SDRAM starting at address
 
86
0xa1700000.  After two blocks have been loaded, it jumps to 0xa1700000.  The
 
87
number of blocks loaded and the load address in SDRAM are hard-coded; only the
 
88
flash offset of the blocks can vary at run-time (based on the presence of the
 
89
magic number).
 
90
 
 
91
In addition to using the docg4's reliable mode, the IPL expects each 512 byte
 
92
page to be written redundantly in the subsequent page.  The hardware is capable
 
93
of detecting bit errors (but not correcting them), and if a bit error is
 
94
detected when a page is read, the page contents are discarded and the subsequent
 
95
page is read.
 
96
 
 
97
Reliable mode reduces the capacity of a block by half, and the redundant pages
 
98
reduce it by half again.  As a result, the normal 256k capacity of a block is
 
99
reduced to 64k for the purposes of the IPL/SPL.
 
100
 
 
101
For the sake of simplicity and uniformity, the u-boot SPL mimics the operation
 
102
of the IPL, and expects the image to be stored in the same format.
 
103
 
 
104
 
 
105
Instructions on Programming u-boot to flash
 
106
===========================================
 
107
 
 
108
To program u-boot to your flash, you will need to boot the Linux kernel on your
 
109
phone using a PalmOS bootloader such as cocoboot.  The details of building and
 
110
running Linux on your Treo (cross-compiling, creating a root filesystem,
 
111
configuring the kernel, etc) are beyond the scope of this document.  The
 
112
remainder of this document describes in detail how to program u-boot to the
 
113
flash using Linux running on the Treo.
 
114
 
 
115
 
 
116
Hardware Prerequisites
 
117
======================
 
118
 
 
119
A Palm Treo 680:
 
120
  (dugh)
 
121
 
 
122
A Palm usb cable:
 
123
  You'll need this to establish a usbtty console connection to u-boot from a
 
124
  desktop PC.  Currently there is no support in u-boot for the pxa27x keypad
 
125
  (coming soon), so a serial link must be used for the console.
 
126
  These cables are still widely available if you don't already have one.
 
127
 
 
128
A Linux desktop PC.
 
129
  You may be able to use Windows for the u-boot console if you have a usb driver
 
130
  that is compatible with the Linux usbserial driver, but for programming u-boot
 
131
  to flash, you'll really want to use a Linux PC.
 
132
 
 
133
 
 
134
Treo-side Software Prerequisites
 
135
================================
 
136
 
 
137
Linux bootloader for PalmOS:
 
138
 
 
139
  Cocoboot is the only one I'm aware of.  If you don't already have this, you
 
140
  can download it from
 
141
  https://download.enlightenment.org/misc/Illume/Treo-650/2008-11-13/sdcard-base.tar.gz
 
142
  which is a compressed tar archive of the contents of an sd card containing
 
143
  cocoboot.  Use mkdosfs to create a fat16 filesystem on the first primary
 
144
  partition of the card, mount the partition, and extract the tar file to it.
 
145
  You will probably need to edit the cocoboot.conf file to customize the
 
146
  parameters passed to the kernel.
 
147
 
 
148
 
 
149
Linux kernel:
 
150
 
 
151
  The kernel on the Treo 680 is still a little rough around the edges, and the
 
152
  official kernel frequently breaks on the Treo :(  A development kernel
 
153
  specifically for the Treo 680 can be found on github:
 
154
    http://github.com/mike-dunn/linux-treo680
 
155
  The master branch of this tree has been tested on the Treo, and I recommend
 
156
  using this kernel for programming u-boot.  As of this writing, there may be a
 
157
  bug in the docg4 nand flash driver that sometimes causes block erasures to
 
158
  fail.  This has been fixed in the above tree.
 
159
 
 
160
  If you choose to use the official kernel, it must contain the docg4 driver that
 
161
  includes the reliable_mode module parameter.  This was a later enhancement to
 
162
  the driver, and was merged to the kernel as of v3.8.  Do not try to use an
 
163
  earlier kernel that contains the docg4 driver without support for writing in
 
164
  reliable mode.  If you try to program u-boot to flash with the docg4 driver
 
165
  loaded without the reliable_mode parameter enabled, you *will* brick your
 
166
  phone!
 
167
 
 
168
  For the purpose of programming u-boot to flash, the following options must be
 
169
  enabled in the Treo kernel's .config:
 
170
 
 
171
     CONFIG_MTD=y
 
172
     CONFIG_MTD_CMDLINE_PARTS=y
 
173
     CONFIG_MTD_CHAR=y
 
174
     CONFIG_MTD_NAND_DOCG4=m
 
175
 
 
176
  Note that the docg4 nand driver is configured as a module, because we will
 
177
  want to load and unload it with reliable_mode enabled or disabled as needed.
 
178
 
 
179
  You will also need to specify mtd partitions on the kernel command line.  In
 
180
  the instructions that follow, we will assume that the flash blocks to which
 
181
  u-boot will be programmed are defined by the second partition on the device.
 
182
  The u-boot config file (include/configs/palmtreo680.h) places the u-boot image
 
183
  at the start of block 6 (offset 0x180000), which is the first writable
 
184
  (non-protected) block on the flash (this is also where the PalmOS SPL starts).
 
185
  The u-boot image occupies four blocks, so to create the u-boot partition, pass
 
186
  this command line to the kernel:
 
187
    mtdparts=Msys_Diskonchip_G4:1536k(protected_part)ro,1024k(bootloader_part),-(filesys_part)
 
188
  This will create three partitions:
 
189
    protected_part: the first six blocks, which are read-only
 
190
    bootloader_part: the next four blocks, for the u-boot image
 
191
    filesys_part: the remainder of the device
 
192
  The mtdchar kernel device driver will use device nodes /dev/mtd0, /dev/mtd1,
 
193
  and /dev/mtd2 for these partitions, respectively.  Ensure that your root file
 
194
  system at least has /dev/mtd1 if you are not running udev or mdev.
 
195
 
 
196
Userspace Utilities:
 
197
 
 
198
  In addition to everything necessary to provide a useful userspace environment
 
199
  (busybox is indispensable, of course), you will need the mtd-utils package on
 
200
  your root filesystem.  I use version 1.5.0 of mtd-utils, and I suggest you use
 
201
  this version as well, or at leat a version very close to this one, as
 
202
  mtd-utils has tended to be fluid.
 
203
 
 
204
  Note that busybox includes a version of mtd-utils.  These are deficient and
 
205
  should not be used.  When you run one of these utilities (nanddump, etc),
 
206
  ensure you are invoking the separate executable from mtd-utils, and not the
 
207
  one built into busybox.  I recommend that you configure busybox with its
 
208
  mtd-utils disabled to avoid any possibility of confusion.
 
209
 
 
210
  You will also need to cross-compile the userspace Linux utility in
 
211
  tools/palmtreo680/flash_u-boot.c, which we will run on the Treo to perform the
 
212
  actual write of the u-boot image to flash.  This utility links against libmtd
 
213
  from the mtd-utils package.
 
214
 
 
215
 
 
216
Desktop PC-side Software Prerequisites
 
217
======================================
 
218
 
 
219
Terminal emulator application:
 
220
  minicom, kermit, etc.
 
221
 
 
222
Linux kernel:
 
223
  Compiled with CONFIG_USB_SERIAL enabled.  Build this as a module.
 
224
 
 
225
 
 
226
Recommended (Not directly related to u-boot)
 
227
============================================
 
228
 
 
229
Working directly on the Treo's tiny screen and keypad is difficult and
 
230
error-prone.  I recommend that you log into the Linux kernel running on your
 
231
Treo from your desktop PC using ethernet over usb.  The desktop's kernel must be
 
232
configured with CONFIG_USB_USBNET, CONFIG_USB_NET_CDCETHER, and
 
233
CONFIG_USB_NET_CDC_SUBSET.  The Treo's kernel will need CONFIG_USB_ETH, and its
 
234
init script will need to start an ssh daemon like dropbear.  Note that the usb0
 
235
network interface will not appear on the desktop PC until the Treo kernel's usb
 
236
ethernet gadget driver has initialized.  You must wait for this to occur (watch
 
237
the PC's kernel log) before you can assign usb0 an ip address and log in to the
 
238
Treo.  If you also build the Treo's kernel with CONFIG_IP_PNP enabled, you can
 
239
pass its ip address on the kernel command line, and obviate the need to
 
240
initialize the network interface in your init script.
 
241
 
 
242
Having the Palm usb cable connected to the host has the added benefit of keeping
 
243
power supplied to your Treo, reducing the drain on the battery.  If something
 
244
goes wrong while you're programming u-boot to the flash, you will have lots of
 
245
time to correct it before the battery dies.
 
246
 
 
247
I have encountered a situation where the kernel is sometimes unable to mount a
 
248
root filesystem on the mmc card due to the mmc controller not initializing in
 
249
time, (and CONFIG_MMC_UNSAFE_RESUME doesn't seem to help) so I recommend that
 
250
you build a minimal root filesystem into the kernel using the kernel's initramfs
 
251
feature (CONFIG_BLK_DEV_INITRD).  If you want your root filesystem on the mmc
 
252
card, your init script can mount and switch_root to the mmc card after a short
 
253
sleep.  But keep in mind that in this case you won't be able to use an mmc card
 
254
to transfer files between your desktop and the Treo once Linux is running.
 
255
Another option for transfering files is to mount an nfs filesystem exported by
 
256
the desktop PC.  For greatest convenience, you can export the root filesystem
 
257
itself from your desktop PC and switch_root to it in your init script.  This
 
258
will work if your initramfs init script contains a loop that waits for you to
 
259
initialize the usb0 network interface on the desktop PC; e.g., loop while a ping
 
260
to the desktop PC returns an error.  After the loop exits, do the nfs mount and
 
261
call switch_root.  (You can not use the kernel nfsroot feature because the
 
262
network will not be up when the kernel expects it to be; i.e., not until you
 
263
configure the usb0 interface on the desktop.)  Use the nfs 'nolock' option when
 
264
mounting to avoid the need to run a portmapper like rpcbind.
 
265
 
 
266
 
 
267
Preliminaries
 
268
=============
 
269
 
 
270
Once Linux is running on your Treo, you may want to perform a few sanity checks
 
271
before programming u-boot.  These checks will verify my assumptions regarding
 
272
all the Treo 680s out there, and also ensure that the flash and mtd-utils are
 
273
working correctly.  If you are impatient and reckless, you may skip this
 
274
section, but see disclaimer at the top of this file!
 
275
 
 
276
Load the docg4 driver:
 
277
 
 
278
  $ modprobe docg4 ignore_badblocks=1 reliable_mode=1
 
279
 
 
280
We tell the driver to use the docg4's "reliable mode" when writing because this
 
281
is the format required by the IPL, which runs from power-up and loads the first
 
282
portion of u-boot.  We must ignore bad blocks because linux mtd uses out-of-band
 
283
(oob) bytes to mark bad blocks, which will cause the blocks written by PalmOS to
 
284
be misidentified as "bad" by libmtd.
 
285
 
 
286
Check the kernel log to ensure that all's well:
 
287
 
 
288
  $ dmesg | tail
 
289
              <... snip ...>
 
290
  docg4 docg4: NAND device: 128MiB Diskonchip G4 detected
 
291
  3 cmdlinepart partitions found on MTD device Msys_Diskonchip_G4
 
292
  Creating 3 MTD partitions on "Msys_Diskonchip_G4":
 
293
  0x000000000000-0x000000180000 : "protected_part"
 
294
  0x000000180000-0x000000280000 : "bootloader_part"
 
295
  0x000000280000-0x000008000000 : "filesys_part"
 
296
 
 
297
Ensure that the partition boundaries are as shown.  (If no partitions are shown,
 
298
did you remember to pass them to the kernel on the command line?)  We will write
 
299
u-boot to bootloader_part, which starts at offset 0x180000 (block 6) and spans 4
 
300
256k blocks.  This partition is accessed through the device node /dev/mtd1.
 
301
 
 
302
The docg4 contains a read-only table that identifies blocks that were marked as
 
303
bad at the factory.  This table is in the page at offset 0x2000, which is within
 
304
the partition protected_part (/dev/mtd0).  There is a slight chance that one or
 
305
more of the four blocks that we will use for u-boot is listed in the table, so
 
306
use nanddump to inspect the table to see if this is the case:
 
307
 
 
308
  $ nanddump -p -l 512 -s 0x2000 -o /dev/mtd0
 
309
  ECC failed: 0
 
310
  ECC corrected: 0
 
311
  Number of bad blocks: 0
 
312
  Number of bbt blocks: 0
 
313
  Block size 262144, page size 512, OOB size 16
 
314
  Dumping data starting at 0x00002000 and ending at 0x00002200...
 
315
  0x00002000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
 
316
              <... snip ...>
 
317
 
 
318
The format of the table is simple: one bit per block, with block numbers
 
319
increasing from left to right, starting with block 0 as the most significant bit
 
320
of the first byte.  A bit will be clear if the corresponding block is bad.  We
 
321
want to use blocks 6 throgh 9, so both of the two least significant bits of the
 
322
first byte must be set, as must the two most significant bits of the second
 
323
byte.  If this is not true in your case (you are very unlucky), you should use
 
324
the first contiguous set of four good blocks after block 6, and adjust the
 
325
partition boundaries accordingly.  You will also have to change the value of
 
326
CONFIG_SYS_NAND_U_BOOT_OFFS in include/configs/palmtreo680.h and recompile
 
327
u-boot.  Because the two blocks loaded by the IPL do not have to be contiguous,
 
328
but our SPL expects them to be, you will need to erase any good blocks that are
 
329
at an offset prior to CONFIG_SYS_NAND_U_BOOT_OFFS, so that the IPL does not find
 
330
the magic number in oob and load it.  Once you have done all this, the
 
331
instructions in this file still apply, except that the instructions below for
 
332
restoring the original PalmOS block contents may need to be modified.
 
333
 
 
334
Next, use nanddump to verify that the PalmOS SPL is where we expect it to be.
 
335
The SPL can be identified by a magic number in the oob bytes of the first page
 
336
of each of the two blocks containing the SPL image.  Pages are 512 bytes in
 
337
size, so to dump the first page, plus the oob:
 
338
 
 
339
  $ nanddump -p -l 512 -s 0 -o /dev/mtd1
 
340
  ECC failed: 0
 
341
  ECC corrected: 0
 
342
  Number of bad blocks: 0
 
343
  Number of bbt blocks: 0
 
344
  Block size 262144, page size 512, OOB size 16
 
345
  Dumping data starting at 0x00000000 and ending at 0x00000200...
 
346
  0x00000000: 0a 00 00 ea 00 00 00 00 00 00 00 00 00 00 00 00
 
347
              <... snip ...>
 
348
  0x000001f0: 13 4c 21 60 13 4d 2a 69 13 4b 29 69 89 1a 99 42
 
349
    OOB Data: 42 49 50 4f 30 30 30 10 3a e2 00 92 be a0 11 ff
 
350
 
 
351
Verify that the first seven bytes of oob data match those in the above line.
 
352
(This is ASCII "BIPO000".)
 
353
 
 
354
Do the same for the next block:
 
355
  $ nanddump -p -l 512 -s 0x40000 -o /dev/mtd1
 
356
 
 
357
The first seven oob bytes in last line should read:
 
358
 
 
359
    OOB Data: 42 49 50 4f 30 30 31 81 db 8e 8f 46 07 9b 59 ff
 
360
 
 
361
(This is ASCII "BIPO001".)
 
362
 
 
363
For additional assurance, verify that the next block does *not* contain SPL
 
364
data.
 
365
 
 
366
  $ nanddump -p -l 512 -s 0x80000 -o /dev/mtd1
 
367
 
 
368
It doesn't matter what the oob contains, as long as the first four bytes are
 
369
*not* ASCII "BIPO".  PalmOS should only be using two blocks for the SPL
 
370
(although we will need four for u-boot).
 
371
 
 
372
If you want, you can back up the contents of bootloader_part to a file.  You may
 
373
be able to restore it later, if desired (see "Restoring PalmOS" below).
 
374
 
 
375
  $ nanddump -l 0x100000 -s 0 -o -f bootloader_part.orig /dev/mtd1
 
376
 
 
377
nanddump will spew voluminous warnings about uncorrectable ecc errors.  This is
 
378
a consequence of reading pages that were written in reliable mode, and is
 
379
expected (these should all occur on pages in odd-numbered 2k regions; i.e.,
 
380
0x800, 0xa00, 0xc00, 0xe00, 0x1800, 0x1a00, ...).  The size of the file
 
381
bootloader_part.orig should be 1081344, which is 2048 pages, each of size 512
 
382
plus 16 oob bytes.  If you are using initramfs for the root filesystem, don't
 
383
forget to copy the file to permanent storage, such as an mmc card.
 
384
 
 
385
If all of the above went well, you can now program u-boot.
 
386
 
 
387
 
 
388
Programming u-boot
 
389
==================
 
390
 
 
391
Our u-boot includes a small SPL that must be prepended to u-boot proper.  From
 
392
the base u-boot source directory on your desktop PC:
 
393
 
 
394
  $ cat spl/u-boot-spl.bin u-boot.bin > u-boot-concat.bin
 
395
 
 
396
cd to the tools/palmtreo680/ directory, and cross-compile flash_u-boot.c for the
 
397
Treo:
 
398
 
 
399
  $(CC) -o flash_u-boot $(CFLAGS) $(INCLUDEPATH) $(LIBPATH) flash_u-boot.c -lmtd
 
400
 
 
401
Substitute variable values from your cross-compilation environment as
 
402
appropriate.  Note that it links to libmtd from mtd-utils, and this must be
 
403
included in $(LIBPATH) and $(INCLUDEPATH).
 
404
 
 
405
Transfer u-boot-concat.bin and the compiled flash_u-boot utility to the Treo's
 
406
root filesystem.  On the Treo, cd to the directory where these files were
 
407
placed.
 
408
 
 
409
Load the docg4 driver if you have not already done so.
 
410
 
 
411
  $ modprobe docg4 ignore_badblocks=1 reliable_mode=1
 
412
 
 
413
Erase the blocks to which we will write u-boot:
 
414
 
 
415
  $ flash_erase /dev/mtd1 0x00 4
 
416
 
 
417
If no errors are reported, write u-boot to the flash:
 
418
 
 
419
  $ ./flash_u-boot u-boot-concat.bin /dev/mtd1
 
420
 
 
421
You can use nanddump (see above) to verify that the data was written.  This
 
422
time, "BIPO" should be seen in the first four oob bytes of the first page of all
 
423
four blocks in /dev/mtd1; i.e., at offsets 0x00000, 0x40000, 0x80000, 0xc0000.
 
424
 
 
425
Shutdown linux, remove and re-insert the battery, hold your breath...
 
426
 
 
427
 
 
428
Enjoying u-boot
 
429
===============
 
430
 
 
431
After you insert the battery, the u-boot splash screen should appear on the lcd
 
432
after a few seconds.  With the usb cable connecting the Treo to your PC, in the
 
433
kernel log of your PC you should see
 
434
 
 
435
  <6>usb 3-1: New USB device found, idVendor=0525, idProduct=a4a6
 
436
  <6>usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
 
437
  <6>usb 3-1: Product: U-Boot 2013.01-00167-gd62ef56-dirty
 
438
  <6>usb 3-1: Manufacturer: Das U-Boot
 
439
 
 
440
Load the usbserial module on your desktop PC:
 
441
 
 
442
  $ modprobe usbserial vendor=0x0525 product=0xa4a6
 
443
 
 
444
and run your favorite terminal emulation utility (minicom, kermit, etc) with the
 
445
serial device set to /dev/ttyUSB0 (assuming this is your only usb serial
 
446
device).  You should be at the u-boot console (type 'help').
 
447
 
 
448
There is not much that is unique about using u-boot on the palm treo 680.
 
449
Kernels can be loaded from mmc, flash, and from the desktop PC via kermit.  You
 
450
can expand the size of the second partition on the flash to contain a kernel, or
 
451
else put the kernel(s) in their own partition.
 
452
 
 
453
Nand commands work as expected, with the excepton that blocks not written by the
 
454
linux mtd subsystem may be misidentified by the u-boot docg4 driver as "bad" if
 
455
they contain data in the oob bytes.  This will be the case for the blocks
 
456
containing the u-boot image, for example.  To work around this, use 'nand scrub'
 
457
instead of 'nand erase' to erase these blocks, and 'nand read.raw' to read them
 
458
to memory.  (It would be useful if u-boot's nand commands provided a way to
 
459
explicitly ignore "bad" blocks, because read.raw does not perform ecc.)  The
 
460
'nand dump' command will read these "bad" blocks, however.
 
461
 
 
462
Currently u-boot itself can only be programmed to flash from Linux; there is no
 
463
support for reliable mode in u-boot's docg4 flash driver.  This should be
 
464
corrected soon.
 
465
 
 
466
 
 
467
Customizing
 
468
===========
 
469
 
 
470
If you change u-boot's configuration significantly (adding or removing
 
471
features), you may have to adjust the value of CONFIG_SYS_NAND_U_BOOT_SIZE.
 
472
This is the size of the concatenated spl + u-boot image, and tells the SPL how
 
473
many flash blocks it needs to load.  It will be rounded up to the next 64k
 
474
boundary (the spl flash block capacity), so it does not have to be exact, but
 
475
you must ensure that it is not less than the actual image size.  If it is larger
 
476
than the image, blocks may be needlessly loaded, but if too small, u-boot may
 
477
only be partially loaded, resulting in a boot failure (bricked phone), so better
 
478
to be too large.  The flash_u-boot utility will work with any size image and
 
479
write the required number of blocks, provided that the partition is large
 
480
enough.
 
481
 
 
482
As the first writable block on the device, block 6 seems to make the most sense
 
483
as the flash offset for writing u-boot (and this is where PalmOS places its
 
484
SPL).  But you can place it elsewhere if you like.  If you do, you need to
 
485
adjust CONFIG_SYS_NAND_U_BOOT_OFFS accordingly, and you must ensure that blocks
 
486
preceeding the ones containing u-boot do *not* have the magic number in oob (the
 
487
IPL looks for this).  In other words, make sure that any blocks that previously
 
488
contained the u-boot image or PalmOS SPL are erased (and optionally written with
 
489
something else) so that the IPL does not load it.  Also make sure that the new
 
490
u-boot starting offset is at the start of a flash partition (check the kernel
 
491
log after loading the docg4 driver), and pass the corresponding mtd device file
 
492
to the flash_u-boot utility.
 
493
 
 
494
The u-boot built-in default environment is used because a writable environment
 
495
in flash did not seem worth the cost of a 256k flash block.  But adding this
 
496
should be straightforward.
 
497
 
 
498
 
 
499
Restoring PalmOS
 
500
================
 
501
 
 
502
If you backed up the contents of bootloader_part flash partition earlier, you
 
503
should be able to restore it with the shell script shown below.  The first two
 
504
blocks of data contain the PalmOS SPL and were written in reliable mode, whereas
 
505
the next two blocks were written in normal mode, so the script has to load and
 
506
unload the docg4 driver.  Make sure that the mtd-utils nandwrite and flash_erase
 
507
are in your path (and are not those from busybox).  Also double-check that the
 
508
backup image file bootloader_part.orig is exactly 1081344 bytes in length.  If
 
509
not, it was not backed up correctly.  Run the script as:
 
510
 
 
511
  ./restore_bootpart bootloader_part.orig /dev/mtd1
 
512
 
 
513
The script will take a minute or so to run.  When it finishes, you may want to
 
514
verify with nanddump that the data looks correct before you cycle power, because
 
515
if the backup or restore failed, your phone will be bricked.  Note that as a
 
516
consequence of reliable mode, the odd-numbered 2k regions in the first two
 
517
blocks will not exactly match the contents of the backup file, (so unfortunately
 
518
we can't simply dump the flash contents to a file and do a binary diff with the
 
519
original back-up image to verify that it was restored correctly).  Also,
 
520
nanddump will report uncorrectable ecc errors when it reads those regions.
 
521
 
 
522
#!/bin/sh
 
523
 
 
524
if [ $# -ne 2 ]; then
 
525
    echo "usage: $0: <image file> <mtd device node>"
 
526
    exit 1
 
527
fi
 
528
 
 
529
# reliable mode used for the first two blocks
 
530
modprobe -r docg4
 
531
modprobe docg4 ignore_badblocks=1 reliable_mode=1 || exit 1
 
532
 
 
533
# erase all four blocks
 
534
flash_erase $2 0 4
 
535
 
 
536
# Program the first two blocks in reliable mode.
 
537
# 2k (4 pages) is written at a time, skipping alternate 2k regions
 
538
# Note that "2k" is 2112 bytes, including 64 oob bytes
 
539
file_ofs=0
 
540
flash_ofs=0
 
541
page=0
 
542
while [ $page -ne 1024 ]; do
 
543
    dd if=$1 bs=2112 skip=$file_ofs count=1 | nandwrite -o -n -s $flash_ofs $2 - || exit 1
 
544
    file_ofs=$((file_ofs+2))
 
545
    flash_ofs=$((flash_ofs+0x1000))
 
546
    page=$((page+8))
 
547
done;
 
548
 
 
549
# normal mode used for the next two blocks
 
550
modprobe -r docg4
 
551
modprobe docg4 ignore_badblocks=1 || exit 1
 
552
dd if=$1 bs=1 skip=$file_ofs count=540672 | nandwrite -o -n -s 0x80000 $2 - || exit 1
 
553
modprobe -r docg4
 
554
 
 
555
TODO
 
556
====
 
557
 
 
558
  - Keypad support.
 
559
  - Interactive boot menu using keypad and lcd.
 
560
  - Add reliable mode support to the u-boot docg4 driver.
 
561
  - U-boot command that will write a new image to the bootloader partition in
 
562
    flash.
 
563
  - Linux FTD support.