Search This Blog

Wednesday, September 24, 2014

Long Winded Manual

I've often criticized the massively long bits of legislation like Obamacare that exceeded 2,000 pages and made it so "[w]e have to pass the bill so that you can find out what is in it."

But it turns out the Obamacare documents are puny relative to a reference manual I've recently had the opportunity (misfortune?) to encounter.  For one of our robot projects, we're using a small inexpensive Single Board Computer (SBC) called the BeagleBone Black, which retails for about $50.  On the BeagleBone Black, the processor is the Texas Instruments AM3358 Sitara System on a Chip (SOC) which retails for a little over $10.

The AM335x Sitara™ Processors Technical Reference Manual for this $10 chip is a whopping 4,966 pages!  I cringe to consider how long the manual for a $500 Intel chip is these days.  I do wonder, if like Obamacare, they had to build the chip to see what was in it!

The reason I was engaged in this light reading was that I was trying to figure out how to set the duty-cycle on the PWM subsystems and right there on page 2,329 was the information I needed:
The value in the active CMPA register is continuously compared to the time-base counter (TBCNT).
When the values are equal, the counter-compare module generates a "time-base counter equal to counter compare A" event.
This event is sent to the action-qualifier where it is qualified and converted it into one or more actions.
Unfortunately, I didn't realize that was what I was looking for as the term "duty-cycle" doesn't appear anywhere.  So I gave up trying to decipher the multi-thousand page manual and instead, I downloaded the source for the linux operating system and in /arm-kernel/linux-dev/KERNEL/drivers/pwm/pwm-tiehrpwm.c there appeared something much easier to understand:

 if (pwm->hwpwm == 1)
  /* Channel 1 configured with compare B register */
  cmp_reg = CMPB;
  /* Channel 0 configured with compare A register */
  cmp_reg = CMPA;

 ehrpwm_write(pc->mmio_base, cmp_reg, duty_cycles);

It's so simple! Just write duty_cycles to cmp_reg, which is either CMPA or CMPB depending on which channel you want to control.  A quick search showed that CMPA has an offset of 12 (hex) and voila, I had all the information I needed!  How exciting! (The sad part is that I really do find that exciting; perhaps you now understand why I so rarely write about technical topics).

I guess that's why I consider English to be my second language, with C being my native tongue, as it's easier for me to search through many tens of thousands of lines of code than to read a handful of pages in a manual to figure something out.  C (and math) are so wonderfully precise while English is mostly gobbledygook as far as I can tell.

Back to the processor. The reason the manual is so long is that the Sitara chip has a lot of random stuff. For example, I imagine that the PWM subsystem I'm using would qualify as random stuff to most people.  The chip has 3 such subsystems to control 3 motors and in this project I'm working on, it coincidentally turns out that I need to control 3 motors.  What are the odds of that?

The chip has all this stuff, but you can only access a fraction of the stuff at any given time.  For example, you can either access the PWM stuff or you can hook up a monitor, but not both.  So most normal people can use this board as an everyday Linux computer (Linux comes pre-installed) with their monitor, keyboard and mouse connected and I can control motors but we can't do both.  No matter what, a large part of any given chip remains unused.

All those logic gates sitting idle.  I find that painful.  A logic gate is a terrible thing to waste!

Yet I can see how it makes sense.  By throwing everything but the kitchen sink onto this chip, they make it so versatile that a lot of people can use it for a lot of different things and that pushes the manufacturing volumes up which pushes the cost down. $50 for a Gigahertz Linux system is pretty good. Right?


Bret said...

This little project is also the reason I've been scarce as of late. I do read all the comments and have enjoyed them immensely.

In another couple of weeks, I should be able to start to participate more.

Clovis e Adri said...

I find this post just as exciting as you describe it, so we must have quite some troubled minds.

BTW, "A logic gate is a terrible thing to waste" makes for a wonderful nerd t-shirt.

Howard said...

BeagleBone Black kicks butt! The intro. video on the website is well done. Crazy processing and on board memory - compare that with $100 per 1MB of RAM on those workstations from 25 years ago.

erp said...

Bret, I'm so glad this little gizmo has made you so happy and also that there are still people like you guys out there figuring things out!

... FYI "normal people" have no idea what you're talking about.


Bret said...

"The Intro. video..."

The video's out of date. It describes Rev. B with a mere 2 GB eMMC memory. Rev. C, which I'm using, has 4 GB, and costs a little more, but 4 GB is enough for a full linux distro.

Bret said...

And sorry AOG, I don't think it runs Windows . . . yet.

Anonymous said...

That's not worst thing. I'm switching jobs (starting October), from consulting/contracting to full time for a Big Tech company, and they are an Apple shop. Oh well - almost all of my development work is on Linux these days so OSX will just be a boot loader for me, to get my Linux VMs operational.

Clovis e Adri said...


I am happy for you.

It turns out Obama's economy is not that bad, uh? :-)

erp said...


Best of everything to you in the next chapter of your life. New adventures are always fun.


Obama's "economy" is one of welfare and dependency. What does that have to do with aog's new job?

Clovis e Adri said...


The provocative joke, pointed out by the smiley, is exactly the suggestion that AOG's good news would have as source Obama's hand, instead of his own.

Anonymous said...


It's been good for a select, lucky few like me. Most people, especially the middle class, are being left behind. It's an excellent trajectory to create millionaires like me along with favelas.

I, personally, consider that a bad result despite my own benefit.

Anonymous said...


It's not really a new adventure - I will be doing basically the same work with the same people, in the same place, just getting a paycheck from a different source. In effect they're becoming my only client :-). My reputation for being easy and pleasant to work with was a big factor (just to tweak Clovis, but still true).

Clovis e Adri said...


It is often true that our virtual persona much differs from our flesh-and-bones one.

You look to prove the rule.

erp said...

Perhaps you'd like to change your moniker from annoying old guy to affable old guy now that it's been revealed that you're really just an old softy.

In any case, may your new venture succeed beyond your wildest expectations.

Anonymous said...


Well, I interact with all of these people almost entirely on line (mostly chat, some email). I rarely meet or even speak with them. None of them live in the same state as I do.

Clovis e Adri said...


Yeah, I can believe you are very competent and efficient on the technical matters you discuss with them. And even easy going - up to the point the topic is not political :-)

Harry Eagar said...

As a professional writer of English, I have often groused that technical manuals are clunky, but that appears to be partly the result of a deficiency of language (which is a convention and the convention was not made for the task); and partly the result of lack of adroitness with vocabulary on the part of the writers.

You use the term 'logic gate,' and even many technically unadept people have a good idea of what you mean; an instance in which the convention was adapted easily to the new machine. But most of the time, not.

As for Obama, it is another example of time travel fallacy to blame him for the destruction of the middle class, which was begun, and intended, by the Reaganites. When you balance capital:labor at 100:0, that's what you get.

Hey Skipper said...

[erp:] Perhaps you'd like to change your moniker from annoying old guy to affable old guy now that it's been revealed that you're really just an old softy.

And I'll take this opportunity to additionally reveal he isn't old, either.

Clovis e Adri said...

What counts as old here, Skipper?