Bone device documentation

Please pardon the newbie question, but I've had no luck with google or
the FAQs:

I have my brand-new Beagle Bone, and it booted up Angstrom just fine.
I see device files for lots of peripheral devices in the /sys
directory. What I haven't been able to find is some sort of
documentation that tells me what the interface to these things is! I
figured out that I can write 1's and 0's to the LED brightness file to
control the user LEDs, but the remaining devices aren't so simple.
What I really need is a reference manual that tells me:

1. How the /sys directory is organized and what I can find where
2. What the interface is to each device file--what commands can I
send, how do I configure hardware, etc.
3. How I talk to the hardware via a C program (i.e., can I mmap the
device files? Can I map the hardware registers directly?)

I haven't been able to find such a reference, which makes me think I'm
missing something more fundamental. Is there something I'm missing
here?

Thanks for the help,

Brian

Please pardon the newbie question, but I've had no luck with google or
the FAQs:

Let me try to answer by throwing in a few extra URLs or keywords you
can Google. It would be most appreciated if you'd reply back with
what you've learned so that I can try to take a newbie's perspective
to attempt improve the documentation.

I have my brand-new Beagle Bone, and it booted up Angstrom just fine.
I see device files for lots of peripheral devices in the /sys
directory. What I haven't been able to find is some sort of
documentation that tells me what the interface to these things is! I
figured out that I can write 1's and 0's to the LED brightness file to
control the user LEDs, but the remaining devices aren't so simple.

Have you gone through the 101 presentations? [1] I admit they aren't
fleshed out to the degree you'd expect from a reference manual, but
they should give you some starting points. In those presentations, I
tried to walk you through where some of the initial kernel
documentation is on the SYSFS entries, namely the kernel ABI
documentation. This mailing list also had some recent discussion on
where to find the GPIO documentation in the kernel.

I'd also recommend [2] and [3]. These are fairly direct attempts to
answer how to explore SYSFS.

[1] http://beagleboard.org/beagleboard101
[2] http://www.beagleboard.org/~arago/education/presentations/Learning_Linux_Tops_Down.pdf
[3] http://beagleboard.org/esc/boston2011/beaconbasicio

What I really need is a reference manual that tells me:

1. How the /sys directory is organized and what I can find where

This is still a bit dynamic until support for the device is 100%
upstream. I've added it on my README.htm to-do list for needed
documentation.

2. What the interface is to each device file--what commands can I
send, how do I configure hardware, etc.

Also added to the list. There are many such generic references for
Linux, but I can see that it makes sense to include the newbie
resources for this product. The resources page [4] hasn't been
updated for a while, but would it at least be useful to include a link
to the Embedded Linux Primer [5] book?

[4] http://beagleboard.org/resources
[5] http://www.embeddedlinuxprimer.com/

3. How I talk to the hardware via a C program (i.e., can I mmap the
device files? Can I map the hardware registers directly?)

Google 'devmem2'. The various device drivers have different various interfaces.

I haven't been able to find such a reference, which makes me think I'm
missing something more fundamental. Is there something I'm missing
here?

Start with "embedded linux" in your searches and you might get a bit
further. I'm not sure what you searched for at this point, so perhaps
you could share that as well. http://beagleboard.org/faq has a link
to a nice page on how to best get your questions answered.

Jason,

Thanks for your quick reply. Your reference [2] was very useful, as was devmem2. Actually, I haven’t tried devmem2 yet, but it looks like I’ll be able to talk to the hardware registers directly that way, so between that and the AM335x manual I can probably do everything.

From a newbie perspective, I think the single most useful thing for me would be an example of how to use each device via sysfs. The LED example is a great start, but how do I (for example) use the the SPI bus? I know I’m supposed to talk to that device file, but I have no idea where to look for a description of what to say. I would have gone to the generic linux documentation for something like a USB port or SD card, but for devices that my desktop PC doesn’t have, I don’t know where to look. Even a list that just has “see linux doc x” for most of the devices would be great.

Also, it’s not immediately obvious what’s implemented via sysfs and what isn’t. For example, I’m still not sure if I can generate a PWM signal through some device driver that’s already implemented, or if I have to read the AM335x manual and talk to the hardware registers directly.

By the way, I don’t want to sound overly critical–I think you guys put together a great product. And I know it’s difficult to get the right perspective to write documentation for newbies like me.

Thanks again,

Brian