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;
 else
  /* 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?