Thursday, August 27, 2015

IAR, Vybrid, Low Power Timer, and Getting Started Example

This is a short blog on a tiny issue I found working with the FreeScale Vybrid Tower evaluation board with the IAR IDE 'Getting Started' example.

The Getting Started example has two interrupts, one for a periodic timer using the Lower Power Timer (0) and a hardware interrupt for a button, SW1.

There are two IRQs, one for the timer, and one for the button.

The button IRQ outputs the number of times the button has been pushed each time the button is pushed. The timer IRQ blinks a blue LED, off for 1/2 second and on for 1/2 second.

I decided to tweak the example. I want to report the value of the timer counter when the button is pushed. I should see a value from 0 to 500, as the periodic timer is set to 1kHz.

I used the existing IAR symbols, LPTMR0->CNR, to read the timer counter.

Each time I pushed the button the value for CNR was 0.

The Low Power Timer documentation in the FreeScale Vybrid reference manual, pg. 1910-1913.

On page 1913, 41.4.5 LPTMR Counter, it states

The CNR cannot be initialized, but can be read at any time. On each read of the CNR, software must first write to the CNR with any value. This will synchronize and register the current value of the CNR into a temporary register. The contents of the temporary register are returned on each read of the CNR.

Thus one must first write to CNR, then read. The write does not change CNR, it just enables the timer counter to be latched into the CNR register when read.

LPTMR0->CNR = 1;
printf("Timer: %d\n:, LPTMR0->CNR);

Unfortunately, the first line of code gives a compiler error. The error states that CNR cannot be modified.

The structure defined in the Getting Started example for the Vybrid tower that defines the LPTMR registers (MVF50GS10MK50.h), CSR, PSR, CMR and CNR. The registers CSR, PSR, and CMR are defined _IO uint32_t. _IO means read/write.

CNR is defined _I uint32_t as read only. Wrong.

The CNR definition must be changed to _IO uint32_t in order to read CNR.

/** LPTMR - Register Layout Typedef */
typedef struct {
  __IO uint32_t CSR;                               /**< Low Power
Timer Control Status Register, offset: 0x0 */
  __IO uint32_t PSR;                               /**< Low Power
Timer Prescale Register, offset: 0x4 */
  __IO uint32_t CMR;                               /**< Low Power
Timer Compare Register, offset: 0x8 */
  __IO  uint32_t CNR;        /* 
__I  uint32_t */   /**< Low Power
Timer Counter Register, offset: 0xC */
} LPTMR_Type;



Oops.

As I said, a tiny issue.

Thursday, August 20, 2015

Yet Another Make Tutorial - VI

Last post we created a framework to build a library, a unit test program, and a production program. Let's make a few changes to introduce the building of a library.

[This is a continuation of posts  III, and III, IV, and V. Make files are found here.]

Building a library requires a different program than clang, clang++, gcc, or g++. The program is called ar, for archive.

The standard arguments are:

ar rvf <libraryname>.a <object files>

Note: gcc (clang) requires, when using the -l switch to build a program, that the library name starts with the three letters lib, and the three letters lib are not supplied with the -l switch. The .a extension is also assumed.

For example:

# Create libmylibrary.
ar rvf libmylibrary.a iseven.o isnumber.o

#Use libmylibrary.a with gcc
gcc -o aprogram -lmylibrary

The ar program will be used for our $(TARGET): $(OBJS_C) $(OBJS_CXX) command in our make file in the lib directory.

The $(TARGET): $(OBJS_C) $(OBJS_CXX) command in the target and unitest directories will have have -lmylibrary added.

In addition, gcc (or clang) needs to know the path to the library. That is supplied with the -L switch (uppercase L). -L../lib/target

Duplicating two hard coded library names is not good coding practice.

In addition, the dependency list has to have the library added.

$(TARGET): $(OBJS_C) $(OBJS_CXX) ../lib/target/libmylibrary.a

Now there are three hard coded locations for the library.

Let's solve this problem using make variables.

One variable can hold the -L path and one variable can hold the -l library name.

But we have a problem, if the variables are defined in the lib directory make file, the variables are not seen by the unitest and target make files as the lib make file is a child of the parent make file. Variables don't flow up from the child make files.

If we define parts of the -L variable and the -l variable in the parent, pass them as variables to the child make file. We only change to the parent make file is the name of the library.

# makefile17

LIB := lib
UNITEST := unitest
TARGET := target
MYLIBRARY := mylibrary

.PHONY: all clean

all: build_unitest build_target

clean:
  $(MAKE) -C $(TARGET) -f makefile17target clean
  $(MAKE) -C $(UNITEST) -f makefile17unitest clean
  $(MAKE) -C $(LIB) -f makefile17lib clean

build_target: build_lib 
  $(MAKE) -C $(TARGET) -f makefile17target LIBRARY=$(MYLIBRARY) LIBDIR=$(LIB)

build_unitest: build_lib
  $(MAKE) -C $(UNITEST) -f makefile17unitest LIBRARY=$(MYLIBRARY) LIBDIR=$(LIB)

build_lib:
  $(MAKE) -C $(LIB) -f makefile17lib LIBRARY=$(MYLIBRARY)


We've added the variable MYLIBRARYWe have added arguments to the make commands.

The argument of the form

<name>=<string>

defines <name> as a variable with the contents of <string>. <name> is a variable that is then available when make is run.

For the build_lib target, makefile17lib will have LIBRARY defined as mylibrary.

We will have a convention in directory names. The directory under lib where libmylibrary.a will be built is target. Yes, it is hard coded. A variable could be created, LIB_DIR_TARGET, but target will be fine for this tutorial.

Below are the other Make16 make files updated to use the new arguments. [Not complete makexx17 files]


# Makefile17lib

# Build the library

LIB_NAME := lib$(LIBRARY).a
TARGET_DIR := target

.PHONY: all clean

all: $(TARGET_DIR)/$(LIB_NAME)

clean:

$(TARGET_DIR)/$(LIB_NAME) :
mkdir -p $(TARGET_DIR)
cd $(TARGET_DIR)
touch $(TARGET_DIR)/$(LIB_NAME)



# makefile17unitest

LIB_NAME := lib$(LIBRARY).a


.PHONY: all clean

all: unitest

clean:

unitest: ../$(LIBDIR)/target/$(LIB_NAME)
echo Build unitest



# makefile17target

# Build the target program

LIB_NAME := lib$(LIBRARY).a

.PHONY: all clean

all: aprogram

clean:

aprogram: ../$(LIBDIR)/target/$(LIB_NAME)
echo Build target


The make files still don't do much, but the framework is coming into shape. We parameterized the library name.

Next post is to add some code. Add the make file commands from makefile15 to build a library, a unit test, and a program.

Next blog  VII.

Saturday, August 15, 2015

Yet Another Make File Tutorial - V

The past four tutorials, III, and III, and IV have created a good make file for a sub-directory of sources and kept the build directories clean and neat, as well as configure make to run a bit faster.

[Again the source for these tutorials is found here.]

Note: These make files are NOT POSIX compliant.

These next tutorial(s) will build a production quality set of make files that handle libraries, unit tests, and the production program. There will be more discussion about compilers, linkers, unit tests, libraries as well as make files. Using make files also solves the requirement of having one button builds for build tools such a Jenkins. These next tutorials will set up a framework for production and unit test programs.

Unit tests are the sanity checkers for programmers. They make you feel good because they prove that you haven't messed up with your last set of changes. But building unit tests and that program you want to ship for $$s with the same code takes some planning.

A unit test program has a main(). Your program has a main(). You can't have two main() functions in the same program.

Solution: A library or libraries for your code that isn't main(). Each library gets a directory. Each unit test gets a directory, and the production program gets a directory. Thus three directories, lib, unitest, and target.

Each directory will need a make file. A master make file is required to 'run' each of the other make files.

This tutorial will introduce new make syntax and features.

Our first make file is not a make file that compiles code. It calls other make files. Some of the more experienced readers will see we are starting down the path to make file recursion, where make calls make.

There is an article detailing this topic here. The argument is to create a single make file instead of series of recursively called make files.

Let's start.

The new directory Make16 is where we start.

# makefile16

LIB := lib
UNITEST := unitest
TARGET := target

.PHONY: all clean

all: build_unitest build_target

clean:
$(MAKE) -C $(TARGET) -f makefile16target clean
$(MAKE) -C $(UNITEST) -f makefile16unitest clean
$(MAKE) -C $(LIB) -f makefile16lib clean

build_target: build_lib 
$(MAKE) -C $(TARGET) -f makefile16target

build_unitest: build_lib
$(MAKE) -C $(UNITEST) -f makefile16unitest

build_lib:
$(MAKE) -C $(LIB) -f makefile16lib    

[Links for more details here.]

The -C switch changes the working directory to the next argument. When using -C the option -w is automatically turned on. The -w option outputs Entering <directory> and Leaving <directory>. This helps with debugging.

The $(MAKE) variable is a special variable of the Gnu Make. As has been said before, this tutorial is NOT writing POSIX make files.

The make files for lib, unitest, and target are below. These are just shells. The make files have no source code. make still outputs its messages. There are no errors and the framework is shown correct.

# Makefile16lib

# Build the library

.PHONY: all clean

all: alibrary

clean:


alibrary:

================

# makefile16unitest

.PHONY: all clean

all: unitest

clean:

unitest:

===============

# makefile16target

# Build the target program

.PHONY: all clean

all: aprogram

clean:

aprogram:


To run enter

make -f makefile16

or

make -f makefile16 clean


If you don't want all of the Entering and Leaving messages, add the -s switch.

make -s -f makefile16

No output appears.

Next blog we'll add more details about the library. VI.


Thursday, August 13, 2015

Yet Another Makefile Tutorial - IV

The three previous tutorials on make files, I, II, and III, discussed the contents of a make file.

This tutorial will discuss the program make itself, some switches, and internals to help with performance.

make has a lot of built in defaults. The defaults can allow one to create a quick make file. No dependencies have to be created. The simple dependency patterns are already defined. For example.

A directory containing *.c files.

$(SRC_LIST) := $(wildcard *.c)
$(OBJ_LIST) := $(SRC_LIST:.c=.o)

aprogram : $(OBJ_LIST)
    gcc $^ -o $@

That's it. make has default dependencies for %o:%c and gcc.

make --help

will show all the arguments supported by make.

-d  Print a lot of debugging information.

The debugging referred to is about patterns and rules. It is not about variables. [You have to use $(info ...) for variables as discussed in II.]

Create an empty make file and debug it.

touch makefile
make -d

A partial output from make is below.

GNU Make 3.82
Built for x86_64-redhat-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Reading makefiles...
Reading makefile `makefile'...
Updating makefiles....
 Considering target file `makefile'.
  Looking for an implicit rule for `makefile'.
  Trying pattern rule with stem `makefile'.
  Trying implicit prerequisite `makefile.o'.
  Trying pattern rule with stem `makefile'.
  Trying implicit prerequisite `makefile.c'.
  Trying pattern rule with stem `makefile'.
  Trying implicit prerequisite `makefile.cc'.
  Trying pattern rule with stem `makefile'.
  Trying implicit prerequisite `makefile.C'.
  Trying pattern rule with stem `makefile'.
. . . . . . . .

Examining the complete listing the following file extensions are found.

c, cc, C, o, cpp, p, f, F, m, r, s, S, mod, sh, v, y, l, and w.

There are many more implicit patterns and rules than one needs for a simple set of C or C++ files.

Processing all the implicit patterns does slowdown make.

-r --no-builtin-rules  Disable built-in implicit rules.

make -d -r

The entire debug output is below.

GNU Make 3.82
Built for x86_64-redhat-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Reading makefiles...
Reading makefile `makefile'...
Updating makefiles....
 Considering target file `makefile'.
  Looking for an implicit rule for `makefile'.
  No implicit rule found for `makefile'.
  Finished prerequisites of target file `makefile'.
 No need to remake target `makefile'.

Let's go back to the Make15 directory and use -d and -r.

make -d -f makefile15

2689 lines of output for 4 files!

Now

make -d -r -f makefile15

Only 152 lines of output.

For a project with just 4 files, the difference between using -r and not using it is probably isn't noticeable, but with a large project using only one or two patterns, -r can save time.

There is a pseudo target that has a similar feature as -r, .SUFFIXES:

Create a make file with just .SUFFIXES:

echo .SUFFIXES: > makefile
makefile -d

Similar short output, but not as short as -r.

Two methods of saving time with make, -r or .SUFFIXES:

Saving time is what make is all about.

A page discussing many of the implicit rules.
https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html

Next post on make files is here, V.

-----------------------------------

P.S. Is there a way to find out ALL the implicit rules and patterns?

Try

make-p

http://stackoverflow.com/questions/16842930/why-does-gnu-make-define-implicit-pattern-and-implicit-suffix-rules

More details on .SUFFIXES:

https://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html



Tuesday, August 11, 2015

Yet Another Make Tutorial - III

In the first Yet Another Make Tutorial a simple make file, makefile10a, was created to handle the organization of a parent directory, a source directory and an include directory. Yet Another Make Tutorial - II updated makefile10a to include sub-directories in the source directory, makefile13, and makefile14.

All files are found in a BitBucket archive here.

Both make files 13 and 14 dealt with only one source file extension *.c and only one compiler gcc.

Here we are going to expand to add C++ source files and clang.

clang is the up and coming compiler that is replacing gcc, part of the LLVM project. clang.llvm.org.

Pre-built images are available for Windows and Linux.

In makefile13, the source files were selected by the statement


SRC_LIST := $(shell find $(SRC_DIR) -name "*.c" -type f)

If we want to use this make file for both C and C++ files changes need to be made.

Typically the compiler options used for building C files are not the same as those used for C++ files, in fact gcc is used for C files and linkage, where g++ is used for C++ files.

We will need a second set of variables to handle C++ files.

We will also create a set of mixed source files, main.cpp, suba.cpp, subc.c, and subd.c.

These new files are found in the folder Make15 of the BitBucket repository.

Something that has been missing from the tutorials is the standard variable names used for the compiler, CC and CXX.

Let's add the CC variable, used to define the C compiler and CXX to define the C++ compiler. The default for make is cc for the C compiler and g++ for the C++ compiler. We will define both just to be clear.

CC = gcc
CXX = g++

Now add the new set of variables for the C++ source files and objects. The C and C++ source files will be mixed together in the same source tree.

SRC_LIST_CXX := $(shell find $(SRC_DIR) -name "*.cpp" -type f)
SRC_DIR_LIST_CXX := $(patsubst %/,%,$(sort $(dir $(SRC_LIST_CXX))))
OBJS_CXX := $(patsubst %.cpp,$(OBJ_DIR)/%.o,$(notdir $(SRC_LIST_CXX)))
DEPS_CXX := $(OBJS_CXX:.o=.d)

Remember to tell make where to find the *.cpp files via vpath.

vpath %.cpp $(SRC_DIR_LIST_CPP)


These updates result in makefile15.

#makefile15
SRC_DIR := src
OBJ_DIR := obj
INC_DIR := inc
SRC_LIST_C := $(shell find $(SRC_DIR) -name "*.c" -type f)
SRC_DIR_LIST_C := $(patsubst %/,%,$(sort $(dir $(SRC_LIST_C))))
OBJS_C := $(patsubst %.c,$(OBJ_DIR)/%.o,$(notdir $(SRC_LIST_C)))
DEPS_C := $(OBJS_C:.o=.d)
SRC_LIST_CXX := $(shell find $(SRC_DIR) -name "*.cpp" -type f)
SRC_DIR_LIST_CXX := $(patsubst %/,%,$(sort $(dir $(SRC_LIST_CXX))))
OBJS_CXX := $(patsubst %.cpp,$(OBJ_DIR)/%.o,$(notdir $(SRC_LIST_CXX)))
DEPS_CXX := $(OBJS_CXX:.o=.d)
TARGET_DIR := target
TARGET := $(TARGET_DIR)/aprogram
vpath %.c $(SRC_DIR_LIST_C)
vpath %.cpp $(SRC_DIR_LIST_CXX)
.PHONY: all clean

CC = gcc
CXX = g++

all: $(TARGET)

clean:
@rm -f $(OBJ_DIR)/*.o $(OBJ_DIR)/*.d
@rm -f $(TARGET)
@rmdir $(OBJ_DIR)
@rmdir $(TARGET_DIR)

$(TARGET): $(OBJS_C) $(OBJS_CXX)
gcc -lstdc++ $^ -o $@

$(OBJ_DIR)/%.o: %.c
$(CC) -c -MMD -I $(INC_DIR) $< -o $@

$(OBJ_DIR)/%.o: %.cpp
$(CXX) -c -MMD -I $(INC_DIR) $< -o $@

REQUIRED_DIRS := $(OBJ_DIR) $(TARGET_DIR)
_MKDIRS := $(shell for d in $(REQUIRED_DIRS); \
 do              \
 mkdir -p $$d;   \
 done)

-include $(DEPS_C)
-include $(DEPS_CXX)

Let's review each of the updates.

The new C++ variables have been discussed above.

The new vpath statement has been discussed above.

The new CC and CXX variables have been discussed above.

$(TARGET): $(OBJS_C) $(OBJS_CXX)
gcc $^ -o $@

The linkage statement adds $(OBJS_CXX). This makes $(TARGET) dependent on the C++ object files as well as the C object files.

$(OBJ_DIR)/%.o: %.cpp
$(CXX) -c -MMD -I $(INC_DIR) $< -o $@

The new dependent statement builds the C++ object files from the C++ sources, specifically *.cpp extensions.

-include $(DEPS_CXX)

Finally, the second -include statement to add the *.d dependencies for C++ files.

[Note: To update to use *.cc or *.cxx extensions one can changes the 'find' statement for  SRC_LIST_CXX and the OBJ_DIR dependency.]

If more than one extension is used, two sets of code mixed together, one can add an additional -name argument using the -o, the or operator.

SRC_LIST_CXX := $(shell find $(SRC_DIR)-type f -name "*.cpp" -o -name "*.cc" )

However, just adding -o -name "*.cc" is not all that is required to handle multiple extensions. Another post will go into the details. Note that a new pattern, another vpath, and the OBJS need updating.

Now lets change to use clang. Simple. Update CC and CXX.


CC = clang

CXX = clang++

Both C and C++ files are handled by clang.

Another step forward to more make know how.

Next blog on make performance, IV.