trying to formalize the BB "validation" procedure

there's still a bunch i want to do in terms of updating version 2 of
the BB validation page here:

http://code.google.com/p/beagleboard/wiki/BeagleboardRevCValidationv2

the old page being here:

http://code.google.com/p/beagleboard/wiki/BeagleboardRevCValidation

  if you want to play along, the plan is to describe, in sufficient
detail, what users can do to verify that their BB is working properly
from the point where they open the box, pull out their new BB, look at
it and think, "um, ok, now what?" sound fair? to that end, i want to
make the *first* part of the validation as simple as possible -- if
something is unnecessary for an initial validation, i want to leave it
until later. and so, to work.

  for an initial validation, i wouldn't ask anyone to reflash
*anything* on their BB. there's no need for that. getting into how
to flash u-boot or the kernel image or a root filesystem is fine, but
it can't affect a board validation so i'm leaning towards ripping out
anything along those lines. in fact, if someone is a new (and
nervous) BB user, really, the *last* thing you want to be asking them
to do is flash their board. that's just *begging* for trouble.
everything they need to do can be done booting off of their SD card --
they can reflash after they have some experience.

  next, regarding the MLO x-loader -- is there any compelling reason
to update that? yes, most instructions i've seen talk about copying
MLO as the first file to your SD card but, as i understand it, by
default, the boot process will use the x-loader on the BB. is there
any reason these days to use a newer x-loader than the one that ships
with the board? if not, i would minimize discussion of it and even
suggest that there's no need to copy it to your SD card. if the one
on the board works just fine, what's the point?

  regarding u-boot, should the validation procedure use a newer u-boot
than the current version on the C3 board (2009.01-dirty (Feb 19 2009 -
12:23:21))? i think it should. numerous postings to this list
constantly suggest that users get a newer version of u-boot. if
that's the case, then the validation procedure should follow suit.
(and, as i'll point out later, some of the u-boot commands have
changed since the feb 2009 version, so it only makes sense to
universally agree to use a much newer loader, no?)

  at this point, the beginning of the validation procedure should ask
the user to format an SD card and copy only:

  * a newer u-boot loader
  * a kernel image
  * a ramdisk.gz
  * a non-flashing (normal) boot.scr
  * optionally, a directory of files to be used for tests after
    booting (audio, video, etc, etc.)

does that make sense? this would represent a completely
non-destructive validation procedure. thoughts? more shortly.

rday

Dears
Excellent effort are being taken up by you in really positive sense.
Many new beginners will be very much thankful to you if it happens in coming days.
This will give real boost to BEAGLE BOARD Community expansion.

BB board validation procedure once is achieved by the beginner, he will be relived off from all tensions (or say frustrations) of Board is ok or not. Once board validation test is ok, he can only concentrate on his development work & error he is committing in his work. This will reduce your load on childish queries being asked by new beginners, which are but natural (you cannot blame them).

Suggestion:
Why not to separate questions from like:
A) Board validation questions
B) Development/ application improvement questions like 1) USB 2) Audio 3) Video 4) Ethernet 5) LCD- Graphic, Alphanumeric 6) Key board 7) Mouse 8) Wireless communication 9) Analog or Digital I/O etc
This type of BIBLE will help to refer the questions & answer easily by the various user.

With best regards & good wishes!

Nandkumar

there is (or should be) a clear distinction between initial
"validation" and everything you can do from then on.

  IMHO, initial board validation represents simply unpacking the
board, plugging it in, then verifying all the bits and pieces up to
the point where you've booted to a linux login prompt. once that's
done, the validation is over and you're ready to start playing.

  in my experience, the most frustrating part of playing with any new
technology is just getting it working. once you have basic
functionality working, the worst is over. but from what i've seen,
most problems involve people not being able to even boot, which is why
i'm keen on updating the validation procedure. in simple terms, board
validation should involve detailed instructions to the point where, if
you follow the instructions to the letter, then things should just
*work*. period. no excuses. no "if that doesn't work, here's
something else you can try."

  anyway, i've updated v2 of the validation page considerably since
this morning:

http://code.google.com/p/beagleboard/wiki/BeagleboardRevCValidationv2

at least the u-boot part, since i'm convinced even beginners want to
see what the u-boot environment looks like. and now, i'm going to
continue drinking wine and waiting for the turkey to roast.

  later.

rday

I think this is definitely the way to go. Ideally the validation
instructions shouldn't
require the user to think.

It would be great if under "Populating the MMC/SD card" there was simply one
option (the non-destructive one you mention).

Instruction on flashing bootloaders can be done elsewhere; as you say
the idea here is just to validate the hardware works.

Other nitpicks:

The "in exactly this order" bit is somewhat confusing. (Or maybe I'm
overthinking it?).

I'm assuming that the files need to reside in a particular place on
the MMC card for
the various levels of bootloaders to fine them? I think it would be
worth explaining
the reason for copying in a given order. (Im pretty sure you could
copy the ramdisk, kernel
and bootscript in any order you pleased and u-boot would be fine).

Also, it is confusing that the files are called one thing on the
server, and something different
when you have to copy them to the MMC card. Can we arrange to call
them the right
thing on the server; one less thing to go wrong for the user.

More comment to follow later...

Cheers,

Benno

[snip]

The "in exactly this order" bit is somewhat confusing. (Or maybe I'm
overthinking it?).

I'm assuming that the files need to reside in a particular place on
the MMC card for
the various levels of bootloaders to fine them? I think it would be
worth explaining
the reason for copying in a given order. (Im pretty sure you could
copy the ramdisk, kernel
and bootscript in any order you pleased and u-boot would be fine).

From what I understand, MLO has to occupy the position of the first entry in the first directory on the media, otherwise it won't be found. It then makes sense (although I don't know there's any hard and fast reason) for u-boot to be the next entry in the directory and after that you're running in a rich environment that the order of the rest of the files doesn't really matter.

Also, it is confusing that the files are called one thing on the
server, and something different
when you have to copy them to the MMC card. Can we arrange to call
them the right
thing on the server; one less thing to go wrong for the user.

Yes, I agree with this, it's a pain to have to rename the files prior to copying them to the SD card, it would be nice to have a .tgz or .zip file with the necessary files in it, and if they're in a .tgz file, then tar will extract them in the order that they are in the tar file, so you can make sure that MLO is the first file in the tarfile and it should end up as the first file in the directory when it's extracted.

Cheers,
Kai

[snip]
> The "in exactly this order" bit is somewhat confusing. (Or maybe I'm
> overthinking it?).
>
> I'm assuming that the files need to reside in a particular place
> on the MMC card for the various levels of bootloaders to fine
> them? I think it would be worth explaining the reason for copying
> in a given order. (Im pretty sure you could copy the ramdisk,
> kernel and bootscript in any order you pleased and u-boot would be
> fine).

From what I understand, MLO has to occupy the position of the first
entry in the first directory on the media, otherwise it won't be
found. It then makes sense (although I don't know there's any hard
and fast reason) for u-boot to be the next entry in the directory
and after that you're running in a rich environment that the order
of the rest of the files doesn't really matter.

  this is pretty much what i understood -- MLO first but, after that,
it doesn't really matter. could someone clarify that? and, as i
asked before, is there *any* compelling reason to override the flash
MLO with one on your SD card? if not, then i'd be tempted to promote
the idea of populating the SD card with only what you truly need. i
am *always* seeing instructions that open with, "copy MLO to your SD
card ..." when there is no good reason for that. or is there? has
the x-loader changed significantly over the last little while?

> Also, it is confusing that the files are called one thing on the
> server, and something different when you have to copy them to the
> MMC card. Can we arrange to call them the right thing on the
> server; one less thing to go wrong for the user.

Yes, I agree with this, it's a pain to have to rename the files
prior to copying them to the SD card, it would be nice to have a
.tgz or .zip file with the necessary files in it, and if they're in
a .tgz file, then tar will extract them in the order that they are
in the tar file, so you can make sure that MLO is the first file in
the tarfile and it should end up as the first file in the directory
when it's extracted.

  i can agree with this only to the extent that it applies to a
canonical directory somewhere which will contain the agreed-upon files
and images for validation. yes, that's good for convenience, but even
beginners should accept that they might have to copy files and rename
them at the same time.

rday

>
> there's still a bunch i want to do in terms of updating version 2
> of the BB validation page here:
>
> Google Code Archive - Long-term storage for Google Code Project Hosting.
>
> the old page being here:
>
> Google Code Archive - Long-term storage for Google Code Project Hosting.
>
> if you want to play along, the plan is to describe, in sufficient
> detail, what users can do to verify that their BB is working
> properly from the point where they open the box, pull out their
> new BB, look at it and think, "um, ok, now what?" sound fair? to
> that end, i want to make the *first* part of the validation as
> simple as possible -- if something is unnecessary for an initial
> validation, i want to leave it until later. and so, to work.
>
> for an initial validation, i wouldn't ask anyone to reflash
> *anything* on their BB. there's no need for that. getting into
> how to flash u-boot or the kernel image or a root filesystem is
> fine, but it can't affect a board validation so i'm leaning
> towards ripping out anything along those lines. in fact, if
> someone is a new (and nervous) BB user, really, the *last* thing
> you want to be asking them to do is flash their board. that's
> just *begging* for trouble. everything they need to do can be done
> booting off of their SD card -- they can reflash after they have
> some experience.
>
> next, regarding the MLO x-loader -- is there any compelling
> reason to update that? yes, most instructions i've seen talk
> about copying MLO as the first file to your SD card but, as i
> understand it, by default, the boot process will use the x-loader
> on the BB. is there any reason these days to use a newer x-loader
> than the one that ships with the board? if not, i would minimize
> discussion of it and even suggest that there's no need to copy it
> to your SD card. if the one on the board works just fine, what's
> the point?
>
> regarding u-boot, should the validation procedure use a newer
> u-boot than the current version on the C3 board (2009.01-dirty
> (Feb 19 2009 - 12:23:21))? i think it should. numerous postings
> to this list constantly suggest that users get a newer version of
> u-boot. if that's the case, then the validation procedure should
> follow suit. (and, as i'll point out later, some of the u-boot
> commands have changed since the feb 2009 version, so it only makes
> sense to universally agree to use a much newer loader, no?)
>
> at this point, the beginning of the validation procedure should
> ask the user to format an SD card and copy only:
>
> * a newer u-boot loader
> * a kernel image
> * a ramdisk.gz
> * a non-flashing (normal) boot.scr
> * optionally, a directory of files to be used for tests after
> booting (audio, video, etc, etc.)
>
> does that make sense? this would represent a completely
> non-destructive validation procedure. thoughts? more shortly.

I think this is definitely the way to go. Ideally the validation
instructions shouldn't require the user to think.

  i'm not sure i'd phrase it quite that way. :slight_smile: i still think it's a
good idea for the users to *think* about what they're doing and to
understand why they're doing it. my obsession these days is with
instructions that should simply *work*.

  i've mentioned this before, but there's little that drives me
crazier than instructions that read:

  * "do X"
  * "if, for some reason, that doesn't work, try Y"

arrrggghhhhhh! should X work or shouldn't it? and if it might not,
then i want to know under *precisely* what conditions it might fail.
anyway, you get the idea.

It would be great if under "Populating the MMC/SD card" there was
simply one option (the non-destructive one you mention).

Instruction on flashing bootloaders can be done elsewhere; as you
say the idea here is just to validate the hardware works.

  agreed. if all we're talking about is an initial "i just unwrapped
my board and want to make sure it works" validation, then everything
should be as simple (and non-destructive) as possible. there is *no*
compelling reason, at that stage, for folks to be doing any
re-flashing.

rday

IMHO, that's what shell scripts are for. first thing i did was copy
all the downloadable validation files and write populate_sd.sh:

Sorry to jump-in at this point but I don't see why all this stuff is needed for a beginner.
I have message [1] in my mailbox. Whenever I need a new SD card I follow
the instructions and that's all for me. No fdisk, no copy first this then this magic.

Best Regards,
Caglar

[1] http://groups.google.com/group/beagleboard/browse_thread/thread/b1c6396ba57bb722?fwc=1&pli=1

a reasonable position ... what do others think? is there really any
need for a validation page, then? or is that the wrong approach?
thoughts?

rday

p.s. i'm still about to post one more piece on validation and then,
depending on what folks think, move on to another topic.

Yes, I definitely think there's a need for a validation page, and in those validation instructions, I would like to also see instructions to flash the the latest firmware to the card as well as a separate part of the instructions.

We need the typical "I just unwrapped my board and want to make sure it works" validation, and this should not flash the board. We also need to, after everything else has been validated, instruct the user how to flash the board, and explain why this needs to be done (most current OS kernels won't boot unless this has been done) and point the user to a current version of the software that needs to be flashed. I suppose that verifying that you can write to the flash and have it survive a reboot is part of the initial testing process anyway.

Cheers,
Kai

I agree... and remember not everyone is with a beagleboard has the
intention of just running Linux on it. Some of us are hacking our own
low-level code, so separating the validation process from 'installing
the latest linux distro' is a good thing.

(Which is not to say I'm opposed to having a linux uimage on and
sdcard for validation testing, just saying 'install linux and try to
use it' isn't a good replacement for validation, or in short, please
keep the current approach!)

Cheers,

Benno

>>>> Yes, I agree with this, it's a pain to have to rename the files
>>>> prior to copying them to the SD card, it would be nice to have a
>>>> .tgz or .zip file with the necessary files in it, and if they're
>>>> in a .tgz file, then tar will extract them in the order that
>>>> they are in the tar file, so you can make sure that MLO is the
>>>> first file in the tarfile and it should end up as the first file
>>>> in the directory when it's extracted.
>>>
>>> i can agree with this only to the extent that it applies to a
>>> canonical directory somewhere which will contain the agreed-upon
>>> files and images for validation. yes, that's good for
>>> convenience, but even beginners should accept that they might have
>>> to copy files and rename them at the same time.
>>
>> Sorry to jump-in at this point but I don't see why all this stuff is
>> needed for a beginner. I have message [1] in my mailbox. Whenever I
>> need a new SD card I follow the instructions and that's all for me.
>> No fdisk, no copy first this then this magic.
>>
>> [1] http://groups.google.com/group/beagleboard/browse_thread/thread/b1c6396ba57bb722?fwc=1&pli=1
>
> a reasonable position ... what do others think? is there really any
> need for a validation page, then? or is that the wrong approach?
> thoughts?

Yes, I definitely think there's a need for a validation page, and in
those validation instructions,

I agree with this. Thanks for your efforts Robert by the way.

I would like to also see instructions
to flash the the latest firmware to the card as well as a separate
part of the instructions.

I do not agree with this. This belongs in my opinion to a separate page.
Maybe link to this page from the end of the article.

[…]

It should be almost as simple as in [1]. I do not know if the narcissus
builds change or will work with the rev C u-boot and x-load for the next
months.

If not, I would suggest to build an image with a Linux version that
works, let people download it and copy it on the SD card.

Even better for validation would be to let this image run certain tests
automatically after being loaded, i. e., play an animation after boot
and play some music, so that people could see this on a connected
monitor or listen to it over plugged in speakers. Or just let them log
in over ssh with a preset username and password to check USB.

After that link to pages with information on how to flash or how to
build their own images.

Bests,

Paul

fair enough, but a good part of the current validation is written
from the perspective of validating *from linux*. without linux,
you're pretty much restricted to validating what you can do from
u-boot, which can still be useful and which i've tried to do.

  or validation can be split into separate pages -- a preliminary one
that applies to *everyone* involving u-boot, then follow-on pages
written on a per-distro basis. the current (arago-based) validation
would be recognized as the canonical (linux-based) validation page,
while people who work with other distros could write validation pages
for *those* distros. hence, splitting up the work. that could work,
and everyone would be happy.

rday

... remember not everyone is with a beagleboard has the intention of
just running Linux on it. Some of us are hacking our own low-level
code, so separating the validation process from 'installing the
latest linux distro' is a good thing.

(Which is not to say I'm opposed to having a linux uimage on and
sdcard for validation testing, just saying 'install linux and try to
use it' isn't a good replacement for validation, or in short, please
keep the current approach!)

fair enough, but a good part of the current validation is written
from the perspective of validating *from linux*. without linux,
you're pretty much restricted to validating what you can do from
u-boot, which can still be useful and which i've tried to do.

No, I didn't communicate my point very well.

I'm saying validating *from linux* is perfectly fine and adequate.

Validating with a specific distro is perfectly fine and adequate.

I'm merely saying that it would be great to not assume that the user
will end up running a specific Linux distro, (or even Linux) on the
beagleboard later.

Which won't happen if the validation is kept to validation, and not
a 'how to setup the beagle board' page.

or validation can be split into separate pages -- a preliminary one
that applies to *everyone* involving u-boot, then follow-on pages
written on a per-distro basis. the current (arago-based) validation
would be recognized as the canonical (linux-based) validation page,
while people who work with other distros could write validation pages
for *those* distros. hence, splitting up the work. that could work,
and everyone would be happy.

I don't think splitting validation is necessary, merely your already proposed
splitting off of 'installation' (including boot-loaders, kernels, user-lands) is
a great idea, and I continue to support that in the face of requests to put more
things on it.

Cheers,

Benno

i also have no interest in feature creep, either, but it just
occurred to me that it would be useful, as part of validation, to boot
to *some* fairly generic form of linux and continue validation in
terms of audio, video and anything else one can think of, for no other
reason than to be able to say, "these things will work properly on
some build of linux for the beagleboard. therefore, if they don't
work for *you*, you should still know that they'll work for
*someone*."

  in short, we have validated various components of your board as
operating properly under linux. therefore, if they don't work
properly under a *different* linux, it's *your* problem, not your
board's.

rday

Exactly. Completely agree.

you know, this was going to be just a brief diversion for me. :slight_smile:

rday