how to find official information on the chip reserved addresses and magic bits?

Question

How can i find from the chip manufacturer the list of magic addresses for several chips? with decent explanations of the values it supports?

I couldn't even figure out the term to call/search for it.

just starting in embedded programming. there's tons of magic bits i have to set to all kinds of things.

usually i'd encounter something:

MOV BLKMGC 0x01

or

REO034 = 0x80; // stops all onboard leds, boot freebsd, makes coffee, do laundy.
               // use 0x81 if you have more white clothes than color ones.

which sometimes has comments explaining what they are doing. I'm mostly taking notes of all of those i find in sample codes. The ones for msp430 launchpad usually are written by nice verbose people with lots of comments and i can even find some of the address maps on the chip family notes, but hardly a comprehensible list. chips more common on Arduinos leaves even more be desired when trying to fully understand that. (granted, i'm still not sure how to search for it :)

The best place i found so far is the header file for the chip i'm using... but even so, take this example:

 void main(void) {
    WDTCTL = WDTPW + WDTHOLD;                 // Stop Watch Dog Timer
    // how 99% of msp430 programs start.

now the header file:

#define WDTCTL_               0x0120    /* Watchdog Timer Control */
sfrw(WDTCTL, WDTCTL_);
/* The bit names have been prefixed with "WDT" */
#define WDTIS0              (0x0001)
#define WDTIS1              (0x0002)
#define WDTSSEL             (0x0004)
#define WDTCNTCL            (0x0008)
#define WDTTMSEL            (0x0010)
#define WDTNMI              (0x0020)
#define WDTNMIES            (0x0040)
#define WDTHOLD             (0x0080)

#define WDTPW               (0x5A00)

/* WDT-interval times [1ms] coded with Bits 0-2 */
/* WDT is clocked by fSMCLK (assumed 1MHz) */
#define WDT_MDLY_32         (WDTPW+WDTTMSEL+WDTCNTCL)                         /* 32ms interval (default) */
#define WDT_MDLY_8          (WDTPW+WDTTMSEL+WDTCNTCL+WDTIS0)                  /* 8ms     " */
#define WDT_MDLY_0_5        (WDTPW+WDTTMSEL+WDTCNTCL+WDTIS1)                  /* 0.5ms   " */
#define WDT_MDLY_0_064      (WDTPW+WDTTMSEL+WDTCNTCL+WDTIS1+WDTIS0)           /* 0.064ms " */
/* WDT is clocked by fACLK (assumed 32KHz) */
#define WDT_ADLY_1000       (WDTPW+WDTTMSEL+WDTCNTCL+WDTSSEL)                 /* 1000ms  " */
#define WDT_ADLY_250        (WDTPW+WDTTMSEL+WDTCNTCL+WDTSSEL+WDTIS0)          /* 250ms   " */
#define WDT_ADLY_16         (WDTPW+WDTTMSEL+WDTCNTCL+WDTSSEL+WDTIS1)          /* 16ms    " */
#define WDT_ADLY_1_9        (WDTPW+WDTTMSEL+WDTCNTCL+WDTSSEL+WDTIS1+WDTIS0)   /* 1.9ms   " */
/* Watchdog mode -> reset after expired time */
/* WDT is clocked by fSMCLK (assumed 1MHz) */
#define WDT_MRST_32         (WDTPW+WDTCNTCL)                                  /* 32ms interval (default) */
#define WDT_MRST_8          (WDTPW+WDTCNTCL+WDTIS0)                           /* 8ms     " */
#define WDT_MRST_0_5        (WDTPW+WDTCNTCL+WDTIS1)                           /* 0.5ms   " */
#define WDT_MRST_0_064      (WDTPW+WDTCNTCL+WDTIS1+WDTIS0)                    /* 0.064ms " */
/* WDT is clocked by fACLK (assumed 32KHz) */
#define WDT_ARST_1000       (WDTPW+WDTCNTCL+WDTSSEL)                          /* 1000ms  " */
#define WDT_ARST_250        (WDTPW+WDTCNTCL+WDTSSEL+WDTIS0)                   /* 250ms   " */
#define WDT_ARST_16         (WDTPW+WDTCNTCL+WDTSSEL+WDTIS1)                   /* 16ms    " */
#define WDT_ARST_1_9        (WDTPW+WDTCNTCL+WDTSSEL+WDTIS1+WDTIS0)            /* 1.9ms   " */

No explanation of the individual bits, no ready-made combination with the most common one.

bonus rant question

since it will always be compiled on powerful, mostly idle, personal computers, why do all compilers/IDE opt to just mimic the user friendliness of bare metal? isn't there tons of better formats to do that? if i'm not going crazy on performance, do i have to know for mundane coding that setting address 0x0120 with the value 0x5A80 stops the watch dog timer? can't the header files/IDE make it be watch_dog_timer( STOP ); to me?

Answer 1

This information is available in the data sheets from the manufacturer. Not all chips have available data sheets¹, so keep that in mind when you pick out a chip.

For an example, let's look at the ATmega48. This is a simple chip with a nice set of basic peripherals.

1. Go to the manufacturer's website and find the product page. You can do a search for it on their website, or you can even use Google, but I've had the most success just clicking through links on the manufacturer's webpage. Go to the "documents" section of the page.

   For the ATmega48, the documents are available at http://www.atmel.com/devices/ATMEGA48.aspx?tab=documents

2. Download the appropriate PDF file. This will probably be called a "datasheet" or a "user manual". It is definitely not an "application note" or an "overview". If the file is smaller than about a meg or less than a hundred pages long, it's probably not the right file.

   For the ATmega48, the document is called "ATmega48/88/168 Complete"

3. The "magic addresses" are called registers. These are IO registers or peripheral registers, not the kind of registers you use when writing user-space programs. Registers are generally unique, and can be read-only, write-only, or read-write.

   For the ATmega48, you can see a list of all registers in section 31 "Register summary". A description of how to use each register can be found under the section describing the relevant peripheral. For example, the GPIO registers are described in section 14 "I/O-ports", with example code both in assembly and C.

Bonus rant: If you want to write watch_dog_timer( STOP ); in your code, you can define the necessary macros and/or functions yourself (preferably functions, unless your compiler is no good, which happens sometimes with embedded systems²).

And I hope you're being sarcastic when you say that bare-metal programming is "user-friendly".

Footnotes:

¹: For example, you can't get the data sheet for the chip on the Raspberry Pi without a large order and an NDA.

²: In my experience, you often want to choose a chip because it has good compiler support, rather than try to find a good compiler for the chip you already have. At least, if you're a hobbyist. GCC targets Atmel and ARM, which is positively luxurious compared to some of the trashy IDEs I've used.

Answer 2

Being an embedded programmer is not all programming. A big part of it is reading documents, schematics, and hacking (the docs and schematics are always wrong or old or whatever, never trust them 100%).

It is a complete mixed bag. Some vendors make (relatively) great documents, some are dreadful, and everything in between up to and including having to give up your first born to get access to a document (well, not quite but almost). Some companies feel there stuff is secret and you have to sign and NDA, and that doesnt mean good documents will come it is the same mixed bag, just harder to get and more responsibility once you have your hands on it. sometimes you have to give up information (name, phone number, etc) to a sales person, that is the worst as you will get a call every week or month until you quit your job or they quit theirs to see if you are ready to buy that thing you asked about or if you want to hear about the new exciting products. I tend to blacklist companies (every product they make) that require that to get at docs, very often their products are not worth buying.

Each companies document solutions are different. You mentioned the msp430, you have to go to one set of docs for the part family and you get names for registers but not addresses, then you have to go to the specific part datasheet to get the addresses that go with the names. I firmly believe that a big reason why Atmel is so popular is because overall their docs are better, their information is there, sometimes not the best docs, but tons of them, tons of app notes, info that other companies wouldnt give out as easily or at all, etc. Not light years ahead of the competition, sometimes only a few percent better, but you just feel it over time that they are just ahead, you dont worry as much when you have to dig into an atmel part compared to someone elses. ARM, same answer, generally very good documentation (but cores not chips, so you may have a great ARM core doc in a bad chip vendors product). Other companies you have to dig through example programs to find things, the docs dont match the example software, etc.

You are basically doing what the rest of us do. Digging through what is available be it a compiler/assembler sources (actually found info about atmel that was hard to find in an assembler data file, then later finally in the atmel doc), schematics, example programs, header files. Eventually you will become aware that some docs are written by non-technical types who have good writing skills, but no clue what the technical terms are in the docs. Documentation will sometimes fall to the person at the bottom of the totem pole, the new hire the person who turned out to not have any productive skills, etc. Not always, but sometimes. And the docs reflect it. Sometimes the example programs are a one size fits all that may have been designed for a common logic block in many chips that has maybe added or removed some features and you are forever scratching your head why the code keeps fiddling with undocumented or reserved bits (those bits probably do something in a prior version of the logic or in a later version of the logic and if you dig around all the products for the company you might find those bits, not that they matter for the chip you are using). I like to change the code and not touch those undocumented bits just to see what happens. One that I really loved (hated) was an api call to start a card where you had to include a path to a firmware file. turns out if you dig through the driver code, the firmware file was for one flavor of card, if you didnt have that flavor of card you didnt need the file at all, but the api entry code required that file to be real, was pretty annoying when I figured that out (rewrote my on driver, much smaller, faster, better suited to what I was doing).

Some bits and some registers you will never ever find out about. Even if you get a job at the company they may not give you access until you have been in the right department the right amount of time. Dont expect that everything you want to know about is available. Some bits are magic, some bit patterns or data are magic, sometimes you just have to go with the flow and do it the way they tell you...check out the visual6502 project, some folks have been waiting their whole career and into retirement to find out why and how some screwy things in that processor worked...

The best thing to do is what you have perhaps already been doing. Buy boards that are geared toward hobbyists, the arduino, the msp430 launchpad, stm32 discovery boards, mbed, raspberry pi, etc. Get the schematic, or look at their web pages and docs to find the part number for the devices, in particular the processor, then go to their page (usually these are chip vendors peddling their product, not always (arduino). Look up that part, find the docs for that part, sometimes many docs, family plus specific chip, etc. Do some googling see if there are open source projects, read those sources. If you are lucky and keep it up you may get to a point in your carreer where you work somewhere that you can influence or drive the designs, docs, samples, etc. Guess what though, even if you worked at Atmel and were the embedded software guru for a microcontroller, you still have to read other companies docs for the other components on the boards you need to build to test or sell your chip. It doesnt end, it is part of the job.

Many sample programs use defines and functions to hide the raw addresses and bits as many programmers want to see things in words or at least not in hex. Personally I prefer the hex or the bits, because I hate having to wade through layers of macros and header files to verify the bits are right. I have the datasheet (hex numbers, bit numbers) on one side of the screen and text editor programming on the other and having the address in hex match the document is a very warm fuzzy feeling. embedded is about accuracy and reliability. In some way shape or form you have to verify your code is rock solid, if you blindly trust too many people with too many layers of macros/defines/functions without checking every bit somehow, you are going to fail, or at least fail more often than someone else in the department that does check and doesnt fail as much. You cant take forever writing your programs of course so you should find your method that combines your preferences for coding style but delivers reliability. One of the things that makes embedded attractive is that freedom you often get, you dont have the rules of the operating system or limitations of application layer access to things, etc. You can do what you want how you want...