Summary

In the previous articles I took you through the first part of the PSoC4 Boot Sequence, then I showed you how the exception vectors got into the flash, lastly I showed you the Start_C() function and how it initializes your program variables.  After that your main() should start, right?  But wait, when does the PSoC get initialized?  Is it magic?  This article answers that question and explains the evil linker trickery __attribute_((constructor(101)) that is used to call the “initialize_psoc()” function.

For many many reasons, one of my heroes is Brian Kernighan.  He just gets “it” and even better, he can explain “it” beautifully.  One of my favorite Kernighan quotes is “Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?”  Our business is hard, really hard and there is absolutely no call for doing things  that make it harder.  Don’t be deluded, obfuscation is not elegance.

Start_c()

As discussed previously, the Reset() function just calls Start_C() whose role in life is to get the C program initialized (the previous article).  Then it calls the function “__libc_init_array” (line 346) and finally it calls main (line 347).  The first time I saw this I thought, wow that is simple.  Then I started wondering, how and when does PSoC become PSoC?  When I look around in the Cm0Start.c file I see a function called “initialize_psoc” (which I will talk about in the next article).  But, there does not appear to be a call to “initialize_psoc()”.  Did I miss it?  Is it even run?

void Start_c(void)
{
    #ifdef CY_BOOT_START_C_CALLBACK
        CyBoot_Start_c_Callback();
    #else
        unsigned regions = __cy_region_num;
        const struct __cy_region *rptr = __cy_regions;

        /* Initialize memory */
        for (regions = __cy_region_num; regions != 0u; regions--)
        {
            uint32 *src = (uint32 *)rptr->init;
            uint32 *dst = (uint32 *)rptr->data;
            unsigned limit = rptr->init_size;
            unsigned count;

            for (count = 0u; count != limit; count += sizeof (uint32))
            {
                *dst = *src;
                dst++;
                src++;
            }
            limit = rptr->zero_size;
            for (count = 0u; count != limit; count += sizeof (uint32))
            {
                *dst = 0u;
                dst++;
            }

            rptr++;
        }

        /* Invoke static objects constructors */
        __libc_init_array();
        (void) main();

        while (1)
        {
            /* If main returns, make sure we don't return. */
        }

    #endif /* CY_BOOT_START_C_CALLBACK */
}

Debugging to initialize_psoc()

To answer the question, “where is initialize_psoc()” called, I put a breakpoint at that function.  When I run the debugger, you can see that it stops at the right place, and you can see in the call stack that the function is called by the function “__libc_init_array()”.  This is the point where things started to get really difficult in my life.

__libc_init_array()

What in the world is this “__libc_init_array()”.  If you look in “Cm0Start.c” on line 219 you will see this block of code.  That means it is somewhere in some library (and not in this file).

/* The static objects constructors initializer */
extern void __libc_init_array(void);

My first thought was that it had something to do with initializing variables, but I realized that we had already done that.  So, what does it do? And how in the world does it call “initialize_psoc()” and where does it come from?  I started the search by right clicking on it and having PSoC Creator take me to the definition.  But, no luck, for some reason we didn’t include the source code for that function.  So, what does the function do?

Well, start by running the debugger and placing a breakpoint at “__libc_init_array”.  When you do that, you can look at the assembly language.  This is the place that I ended up spending a bunch of time as I had never written ARM assembly, and in fact the last time that I wrote any material amount of assembly was at Georgia Tech 26 years ago.

As I often do, I started by reading a few books and a Cypress application note.  Then I spent a few days writing simple C, compiling it, and looking at the results.  Specifically

• “Embedded Systems with ARM Cortex-M Microcontrollers in Assembly Language and C” by Dr. Yifeng Zhu
• “ARM Assembly Language – Fundamentals and Techniques”, William Hohl & Christopher Hinds
• “AN89610 – PSoC® 4 and PSoC 5LP ARM® Cortex® Code Optimization“

Finally I was ready to dig back into this crazy code.  This function has three sections:

• 0x0620 –> 0x0x0630 is a loop that loads an array of function pointers, then makes the function call to each one (line 0x0636)
• 0x063c is a call to a function called “_init” (which I don’t know what it does)
• 0x0640 –> 0x0x0658 is a loop that loads an array of function pointers, then makes the call to each one (line 0x0654)

0x00000620 <__libc_init_array>:
0x00000620 ldr	r3, [pc, #38]	; (65c <__libc_init_array+0x3c>)
0x00000622 push	{r4, r5, r6, lr}
0x00000624 movs	r5, #0
0x00000626 adds	r6, r3, #0
0x00000628 ldr	r4, [pc, #34]	; (660 <__libc_init_array+0x40>)
0x0000062A subs	r4, r4, r3
0x0000062C asrs	r4, r4, #2
0x0000062E cmp	r5, r4
0x00000630 beq.n	63c <__libc_init_array+0x1c>
0x00000632 lsls	r3, r5, #2
0x00000634 ldr	r3, [r6, r3]
0x00000636 blx	r3
0x00000638 adds	r5, #1
0x0000063A b.n	62e <__libc_init_array+0xe>
0x0000063C bl	6d8 <_init>
0x00000640 ldr	r3, [pc, #20]	; (664 <__libc_init_array+0x44>)
0x00000642 movs	r5, #0
0x00000644 adds	r6, r3, #0
0x00000646 ldr	r4, [pc, #20]	; (668 <__libc_init_array+0x48>)
0x00000648 subs	r4, r4, r3
0x0000064A asrs	r4, r4, #2
0x0000064C cmp	r5, r4
0x0000064E beq.n	65a <__libc_init_array+0x3a>
0x00000650 lsls	r3, r5, #2
0x00000652 ldr	r3, [r6, r3]
0x00000654 blx	r3
0x00000656 adds	r5, #1
0x00000658 b.n	64c <__libc_init_array+0x2c>
0x0000065A pop	{r4, r5, r6, pc}
0x0000065C .word	0x000006e4
0x00000660 .word	0x000006e4
0x00000664 .word	0x000006e4
0x00000668 .word	0x000006ec

What all of this means is that there are two arrays of function pointers.  The first array starts a 0x06e4 and ends at 0x6e4 (in other words it is empty).  The second array starts at 0x06e4 and ends at 0x06ec which means there are two function pointers.

When I look at the memory location 0x06e4 –> 0x06ec you see that there are two address 0x0129 and 0x01bc. (look at the memory window in the picture below).  When I scroll the assembly window to location 0x01bc, look what I find, “initialize_psoc”.

After all of that, I did what I probably should have done originally.  I googled “__libc_init_array source”.  One of the first few google hits was a link to the source code from CodeSourcery.  And it is indeed what I said it was:

• A loop (lines 32-34) with function pointer calls
• A call to “_init” (line 36)
• Another loop (lines 38-40) with function pointer calls

/*                                             
 * Copyright (C) 2004 CodeSourcery, LLC                        
 *                                                            
 * Permission to use, copy, modify, and distribute this file   
 * for any purpose is hereby granted without fee, provided that
 * the above copyright notice and this notice appears in all            
 * copies.                                          
 * This file is distributed WITHOUT ANY WARRANTY; without even the implied 
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 */

/* Handle ELF .{pre_init,init,fini}_array sections.  */
#include <sys/types.h>

#ifdef HAVE_INITFINI_ARRAY

/* These magic symbols are provided by the linker.  */
extern void (*__preinit_array_start []) (void) __attribute__((weak));
extern void (*__preinit_array_end []) (void) __attribute__((weak));
extern void (*__init_array_start []) (void) __attribute__((weak));
extern void (*__init_array_end []) (void) __attribute__((weak));

extern void _init (void);

/* Iterate over all the init routines.  */
void
__libc_init_array (void)
{
  size_t count;
  size_t i;

  count = __preinit_array_end - __preinit_array_start;
  for (i = 0; i < count; i++)
    __preinit_array_start[i] ();

  _init ();

  count = __init_array_end - __init_array_start;
  for (i = 0; i < count; i++)
    __init_array_start[i] ();
}
#endif

Now I need to figure out how the address of the function “initialize_psoc” got into the memory in the table.

__attribute_((constructor(101)))

In the function “_libc_init_array” (above) it iterates through all of the function pointers that are in the array that starts at “__init_array_start” and ends at “__init_array_end”.  If you look at the linker script you will see that it puts the address of every function that is in the section ending with “.init_array.*”  That is cool but how does “intialize_psoc” get in that section?

      . = ALIGN(4);
      KEEP(*(.init))

      . = ALIGN(4);
      __preinit_array_start = .;
      KEEP (*(.preinit_array))
      __preinit_array_end = .;

      . = ALIGN(4);
      __init_array_start = .;
      KEEP (*(SORT(.init_array.*)))
      KEEP (*(.init_array))
      __init_array_end = .;

      . = ALIGN(4);
      KEEP(*(.fini))

      . = ALIGN(4);
      __fini_array_start = .;
      KEEP (*(.fini_array))
      KEEP (*(SORT(.fini_array.*)))
      __fini_array_end = .;

Well… if you look at the “initialize_psoc” function in Cm0Start.c you see a bunch of compiler garbly-gook.  It says if you are using the GNU compiler that you should add the attribute “constructor(101)” to the function.

/*******************************************************************************
* Function Name: initialize_psoc
****************************************************************************//**
*
* This function is used to initialize the PSoC chip before calling main.
*
*******************************************************************************/
#if(defined(__GNUC__) && !defined(__ARMCC_VERSION))
__attribute__ ((constructor(101)))
#endif  /* (defined(__GNUC__) && !defined(__ARMCC_VERSION)) */
void initialize_psoc(void)
{

But what does the “constructor” attribute do?  The answer to that can be found in the ARM Information Center.  Basically it says that it will call all functions with that attribute before main in the order of the attribute value (in this case 101).  The compiler achieves this objective by putting the function in the “.init_array” section.  Then the linker does its magic.

As I said earlier in this post I am really not a fan.  There is absolutely no reason why we should not have just called “initialize_psoc” right before we call “main”.   This would have greatly simplified this file as there must be a similar trick going on with IAR and MDK (but I am not going to go figure it out).  In addition hardcoding that 101 means that someone else might slam into it unexpectedly.

Oh well.  In the next article I will talk about what initialize_psoc actually does.

Summary

In the previous articles, I took you through the first part of the PSoC4 Boot Sequence.  I traced from the power on of the chip to the beginning of the “Reset()” function.  Then in the 2nd article I showed you how the exception vectors were placed into the ROM (Flash).  In this article I will show you the steps taken to initialize the system so that your C program runs correctly.

PSoC4 Boot Sequence: Initialize C Global Variables

RAM is a volatile storage area, meaning that when the chip turns on it is in an indeterminate state.  But, what happens when you define a global variable that resides in the RAM, because it can change, and is also initialized.  Consider this block of code:

We know that when this program starts that the variable “aGlobal” has the value of 10.  But aGlobal can change, so it must be in the RAM and everything in the RAM is scrambled when the PSoC4 is Reset.  We are left with the question: How does the variable aGlobal get to be 10?  Lets start with the listing file for main (which as I discussed in the previous article is called main.lst and can be seen in the Results tab inside of folder “Listing Files”.  Here is the section of code that is material to the definition of aGlobal.

Line 87 is creates an assembler label called “aGlobal” (which matches our variable name).  Then line 88 inserts 4-bytes (aka the size of an integer) with the value (0x0000000A) [dont forget that it is little endian] into the current segment.  Line 82 defines the current segment to be “.data”.  Now lets look at the linker map file where you can see that the final address of “aGlobal” is 0x200000c4.

If you run the debugger you can see that by examining the memory at 0x200000c4

But that address is in the RAM (not the flash).  So how does that address end up with the value of 0x0A like we assigned in the program?

PSoC4 Boot Sequence: Start_c()

It turns out that the only function called by the Reset() function is the Start_c() function. This function does four things

• Initializes the memory (as it says on line 321)
• Invoke static objects constructors (as it says on line 345)… what in the world does this mean? (the subject of the next two articles)
• Calls main() a.k.a the start of your program
• If something bad happens and you return from main then it does an infinite while(1); loop (lines 349-351)

PSoC4 Boot Sequence: Initialize the Memory

To answer the question how does 0x0A get into 0x200000c4 the first thing to do is look at the linker script.  After looking around in the linker script I find that .data section on lines 214-237.  On line 237 it has a tricky little command, specifically “>ram AT>rom”.  This tells the linker to assign addresses in the RAM region, but to load the data in ROM region.

For the purposes of initializing the memory, a __cy_region is a block of memory that has an initialized part (aka a .data section) and a part that is initialized to 0 (aka .bss section).  You can see this in the definition of the __cy_region structure which is declared on line 224 of Cm0Start.c

On line 322 of the function Start_C() you can see that there is a loop over all of the __cy_regions.  On lines 329-334 it copies from the ROM to the RAM.  The on lines 336-340 it initializes the BSS to 0.

After all of that we are left with is figuring out how an array of __cy_region structures get into the Flash and how the symbols __cy_regions and __cy_region_num are set.  For the answer to that question we are back to the linker script.  All of these symbols we have met earlier in this article.

Finally, __cy_region_num is defined on line 62.  This calculation works by calculating the size of the __cy_regions array and dividing it by a hardcoded value for the sizeof(__cy_region) (remember it is a pointer, pointer, int, int which are all 4bytes).  I am not a giant fan of this as if someone changed the structure definition in Cm0Start.c the hardcoded 16 will break.

The __cy_regions was made as an array to future proof the system.  I do not believe that there is ever more than one region initialized by this method.

In this next article I will answer the question “What in the world is that __libc_init_array() function?”

Summary of the PSoC4 Boot Sequence

In the previous post I took you through the first part of the PSoC4 Boot Sequence.  I traced from the power on of the chip to the beginning of the “Reset()” function.  In this post I will trace the steps that were required to get the reset vector and stack pointer set and programmed into the flash of the PSoC4 at the right place.

We know that you program the chip with a hex file which is essentially a file with a list of addresses and values.  But how to you get a hex file?  And how do you get the Reset Vector and Stack Pointer into the hex file?  In order to create a hex file there are several steps required.

1. Compile C –> Assembly Listing File then Assemble listing –> Objectfiles
2. Link object files –> into ELF file
3. Convert ELF –> Hex file

PSoC4 Boot Sequence: Compile and Assemble Program

Each C file in your project is turned into an ARM assembly language program by the compiler.  You can see the ARM assembly language programs in “.lst” files.  You can find your project listing files by clicking on the “Results” tab in the workplace explorer then selecting the “listing files” folder under your project.  In the screenshot below I am showing you the “Cm0Start.lst” which is the ARM assembly language file from the Cm0Start.c.  You will notice that there is one listing file for each of the C files in your project.

The next step in the process is for the Assembler to turns the listing files into object files.  Each object file has the hex bytes that represent your program and data.  It also defines which “section” that the code and data belong too.  The .0 also has a list of symbols that it doesn’t know the address of e.g. the address of functions and data in other files.  In order to see the object files you need to use the windows explorer (we don’t attach them to the workplace explorer)

PSoC4 Boot Sequence: Linker Configuration

The linker is responsible for:

1. Combining all of the .o files into one file
2. Assigning actual addresses for all of the symbols e.g. variables and functions

In order for the linker to do its job, it needs a linker script.  Cypress supports three toolchains: GCC, ARM MDK and IAR.  Each one of the toolchains has different syntax, form etc. for the linker script.  This is painful, but it is made worse by the fact that the linker script language is rather esoteric.  PSoC Creator makes a linker script for all three of the tool chains.  You can find those files called “cm0gcc.ld” (the GCC linker file), Cm0Iar.icf (the IAR linker file) and Cm0RealView.scat (the MDK linker file) in the workspace explorer under Generated_Source–>PSoC4–>cy_boot

There is quite a bit going on in the linker file.  In fact the GCC linker file for PSoC4M is 470 lines long.  However, there are two basic commands in the linker file.

The “Memory” command which defines the address and size of the different types of memory in the system.  Each block of memory is sometimes called a “region”, but the Linker words “region” and “section” and “segment” are used somewhat erratically in the parlance.  In this PSoC4M there is 128K of Flash that starts at address 0x00000000 and 16K of RAM which starts at address 0x20000000.  You can see the “Memory” command on lines 29-33 of the GCC linker script.

The second big command in the linker file is “SECTIONS”.  After the sections command there is a list of [input] section names and where they belong (aka their address).   When you look around on the internet you will find that sometimes the word “section” is used interchangeably with the word “segment”.  Unfortunately there does not appear to be a canonical definition of either of these words. There are three main section/segments

• bss – this section contains variables which should be initialized to zero before main starts
• data – this section contains variables which need to be initialized to some specific value
• text – this section contains your program

Here is a screenshot of the part of the GCC linker file that includes the definition of where the PSoC4 ARM exception vectors are located.  This starts on line 72 where the “SECTIONS” command is issued.

The section command defines the a list of sections and the address of the sections.  Inside of the linker there is an “address pointer” which keeps track the current address in the system.  As it loads sections into the program it increments the address pointer so that it knows the final address of symbols.

In the above listing you see on line 87 that a section called “.text” belongs starting at address “appl_start”.  The linker code on lines 75–>80 is used to support bootloading programs with multiple application.  However, in this case we have only one application and no bootloader.  As a result nothing is loaded and “appl_start” is set to 0x00000000 which is also known as the first location in Flash.  Line 92 tells the linker to put the code in the section “*.romvectors” next.  Now we need to find the code that is marked in some .c file as belonging to the section “romvectors”.  I will come back to the linker script in a later article.

Cm0Start.c the Heart of the PSoC4 Boot Sequence

After digging through the beginning of the linker script and putting a breakpoint on the reset vector we know that the vector table is in a section named “romvectors” and we know that the 2nd entry in the table is the address of the function “Reset()”.  So that leaves us with the question:  Where are the “romvectors” defined?  After using the PSoC Creator search functionality I find this block of code.

That nested mess of #defines and #ifdefs is a bit intimidating… but it was all put there to support the three different compilers.  If you boil it down, the first thing you will see is line 462 tells the compiler to put the next block of code into the “.romvectors” section.  Bingo! that is exactly what we were looking for.  Then on line 464 you can see that we define an array of type “cysisraddress”.  It turns out that “cyisraddress” is just a function pointer.  OK.

Now dig a little bit more and you can see that line 467 defines the address of the initial stack pointer as CY_SYS_INITIAL_STACK_POINTER.  This address is the last location in the RAM.  Then on line 471 we put the address of the Reset() function, then we put in two entries for the NMI and hard fault handers.  The “IntDefaultHandler” is an infinite while(1){} which hangs the processor.  This function is also in the Cm0Start.c file.

Stack Pointer

Earlier I said “.. the address of the initial stack pointer.  This address is the last location in the RAM.”  How does that get to be?  Well if you hover over CY_SYS_INITIAL_STACK_POINTER you will find that it is a #define for the symbol “__cy_stack”.  Then when you look in the linker script you will find:

You can also see that the end of the heap is defined as the address of __cy_stack – 0x800.   The 0x800 must be the size of the stack… and it is… you define it in on the system resources tab of the “design wide resources”

The final thing to look at with regards to the stack is linker file definition of the stack (and heap).  On line 258 you can see that the stack starts at the address __cystack – 0x800.  This address is also known as the end of the RAM minus the size of the stack (remember that in ARM the stack builds down towards lower addresses)

Test1.map

The last link in the chain is the linker map file.  You can find that file in the Test1–>CortexM0–>ARM_GCC_541–>Debug–>Listing Files directory.  The map file is message output file of the linker.  You can see the final resting place of all of the symbols. In the screenshot below you can see that the “.romvectors” segment started at address 0x0 and ended at address 0x10.  This makes sense as there are 4x 4 byte addresses (stack pointer, reset vector, NMI vector, Hard Fault vector)

And the stack landed at 0x200038000 and ends at 0x20004000 which makes sense as we have 16K of SRAM aka 0x4000 bytes.

In the next post we will follow through the “Reset()” function and the initialization of the BSS&Data section as well as the C-Standard library.

Summary

Recently I have been working on RTOSs.  While I was completing the port of FreeRTOS, I ran into something that I just didn’t understand.  So, I called a close friend who is a remarkable programmer.  Instead of telling me the answer, he said “I could tell you, or you could set a breakpoint on the reset vector and find out for yourself”.  This simple statement sent me into weeks of single stepping ARM assembly language, reading linker scripts, reading application notes and crawling through boot source code to figure out what is really happening during the PSoC4 Boot Sequence.

So, what happens when power is applied to a PSoC4?  I suppose that I could tell you to “Set a breakpoint on the reset vector and find out for yourself.”  Which would be a good thing for you to do, but it would’nt make for very interesting reading.  It also wouldn’t tell the whole story as what I am going to show you is what happens after the initial supervisory part of the boot occurs.

In this series posts I will take you through the process.

1. Using the debugger: Setting a breakpoint on the reset vector of PSoC4 Boot Sequence
2. Creating the Exception Table using the Linker
3. Generated Source & cy_boot & Cm0Start.c
4. RAM Vectors –> RAM Vectors
5. Start_c
6. initialize_psoc
7. Solving the mystery of  __libc_init_array & a GCC trick

The whole process relies heavily on the linker script to get all of the code and vectors into the right place.  If you have never dug through a linker script, it can be a bit overwhelming, but don’t despair as I will explain the parts required to make this work.

All that being said, the PSoC4 Boot Sequence must:

1. Move the Flash based exception vector table to the RAM (so that it can be changed)
2. Startup the C Standard library environment
3. Initialize the C-variables (from the Data segment) and zero the ones in the BSS segment.
4. Move the table of PSoC flash based register settings into the appropriate volatile latches (make the PSoC a PSoC)

Using the debugger: Setting a breakpoint in the reset vector of PSoC4 Boot Sequence

The first thing that I did was create a blank PSoC4 M project with a blinking LED.  I then clicked the debug button which built the project, programmed it into the board, then started the debugger.  When you do that, here is what you will see.  You can see that the debugger by default boots the chip and runs until the first line in main (which is beyond the reset vector)

But I want to break on the reset the vector.  I didn’t even know what function Cypress had setup for the reset vector or exactly where to look for it.  I knew that  I needed to figure out where the reset vector is located in the CM0 so that I could put a breakpoint on that location. Start by googling “arm cortex m0 reset vector”  The first google hit is an ARM page that shows the layout of all of the exception vectors:

The reset vector is at address 0x04.  Now examine the memory in the debugger to find the address (which you can see is 0x00000011 – don’t forget that this processor is little endian). You can examine the memory by clicking the “Memory 1” tab at the bottom of the debugger.

Create an address based breakpoint by using the debug->New Breakpoint menu.

Then press the reset button (which I highlighted in Red) on the debugger.  This will cause a reset of the chip, the PSoC4 ARM Cortex-M0 will load the program counter (PC) and start running. You will end up on a screen that looks like this:

That is a pretty convenient place to stop.  The function is called “Reset” which makes good sense, and it is in a file called “Cm0Start.c”.  When I saw this, I thought that the whole exercise was going to be a cakewalk, little did I know that I was about to fall into a rabbit hole, that was going to take a few weeks to descend out of.

In the next post I will show you where the reset vector came from and how it and stack pointer got into the flash.