csal: Documentation and makefile updates.

Created master makefile in root directory of project.
Added architecture detection and cross-compile include makefile.

Updated documentation for build process and project directory structure.

Version revision to 2.3

Ensure all source files contain apache license statement.

Signed-off-by: Mike Leach <[email protected]>

README.md

@@ -46,12 +46,17 @@ Library supplied as a git repository on github - [email protected]:ARM-software/CSA
 
 `./build`  : The main library build `Makefile`. Change to this directory to build the library.
 
-`./python` : Build and source files to make a python module to interface to the library.
+`./python` : Build and source files to make a python module to interface to the library. (unmaintained)
+
+`./experimental` : Unmaintained and unsupported additional demos.
 
 `./doxygen-cfg.txt` : File to generate API documentation using __doxygen__.
 
 `./README.md` : This readme text file - which is also processed by __doxygen__.
 
+`./makefile`  : master makefile - `make help` for list of targets.
+
+
 Documentation
 -------------
 
@@ -145,10 +150,11 @@ Updates to APIs:-
 - Updated topology detection to recognise an Embedded Logic Analyser type component.
 - Updated documentation for running Juno examples an shipping scripts to set up the platform.
 
-Version 3.0.0
+Version 2.3
 -------------
 - Transfer to github project
-- Versioning change
+- makefile updates for x-compile and master makefile in project root dir.
+- moved some code to 'experimental' directory - demos that are not maintained / supported. 
 
 ------------------------------------
 

build/makefile

@@ -1,8 +1,25 @@
-# CoreSight Access Library
+#############################################################################
+#  CoreSight Access Library
+#
+#  Copyright (C) ARM Limited, 2017. All rights reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at#
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#############################################################################
 # 
 # This makefile builds the CS-Access library for both static and dynamic linked versions. 
 #
-# Default builds the standard release versions, linux application space
+# Default builds the standard release versions, linux application space, arm 32 arch
 #
 # to build debug add DEBUG=1 to the make command line
 # to build in the v7 debug halt extensions add DBG_HALT=1 to the make command line
@@ -12,24 +29,27 @@
 # make DEBUG=1 
 #  
 
-# default settings
-CC=gcc
+# setup architecture & x-compile
+include ../makefile-arch.inc
+
+# default settings - allow for cross compile of library 
+CC=$(CROSS_COMPILE)gcc
 CFLAGS=-Wall -Wno-switch
 
-LIB_DIR = ../lib/rel
-LIB_DIR_BM=../lib/rel_bm
+LIB_DIR = ../lib/$(ARCH)/rel
+LIB_DIR_BM=../lib/$(ARCH)/rel_bm
 LIB_NAME=csaccess
 LIB_NAME_UTIL=csacc_util
-BUILD_DIR=./rel
-BUILD_DIR_BM=./rel_bm
+BUILD_DIR=./rel-$(ARCH)
+BUILD_DIR_BM=./rel_bm-$(ARCH)
 
 # build options
 ifeq ($(DEBUG),1)
 CFLAGS+= -O0 -DDEBUG -g
-LIB_DIR = ../lib/dbg
-LIB_DIR_BM = ../lib/dbg_bm
-BUILD_DIR=./dbg
-BUILD_DIR_BM=./dbg_bm
+LIB_DIR = ../lib/$(ARCH)/dbg
+LIB_DIR_BM = ../lib/$(ARCH)/dbg_bm
+BUILD_DIR=./dbg-$(ARCH)
+BUILD_DIR_BM=./dbg_bm-$(ARCH)
 else
 CFLAGS+= -O2 -DNDEBUG
 endif
@@ -47,14 +67,19 @@ CFLAGS+= -DUSING_V7_DBG_HALT
 CSSRC_HALT=cs_debug_halt.c
 endif
 
-# LPAE options
+# check if building on/for aarch64
+ifeq ($(ARCH),arm64)
+CFLAGS+= -DCS_VA64BIT
+ifneq ($(NOLPAE),1)
+CFLAGS+= -DLPAE
+endif
+
+else
+# arm 32 - might want lpae
 ifeq ($(LPAE),1)
 CFLAGS+= -DLPAE
 endif
 
-# 64 bit VAs
-ifeq ($(VA64),1)
-CFLAGS+= -DCS_VA64BIT
 endif
 
 #disable diagnostic printing
@@ -113,7 +138,14 @@ SO_OBJS_UTIL=$(addprefix $(BUILD_DIR)/so/,$(CSUTILSRC:%.c=%.o))
 
 # build both lib types
 .PHONY: all
-all: lib_a lib_so 
+all: start lib_a lib_so 
+
+# start msg
+start:
+	@echo "CSAL libraries: Building ARCH=$(ARCH), CROSS_COMPILE=$(CROSS_COMPILE)"
+	@echo "MAKEFLAGS = $(MAKEFLAGS)"
+	@echo ""
+
 
 # create the lib output and build dirs
 .PHONY: lib_dir
@@ -157,26 +189,4 @@ clean_objs:
 	rm -fr $(SO_OBJS)
 	rm -fr $(SO_OBJS_UTIL)
 
-###### library maintenance operaions ##################################
-
-# CS Lib API Documentation
-docs: ../doxygen-cfg.txt 
-	cd ../. && doxygen doxygen-cfg.txt 
-
-
-# create a distribution file.
-libsources = ../source ../include ../build/Makefile ../build/readme_build.md
-demosources = ../demos/*.c ../demos/*.h ../demos/Makefile ../demos/readme_demos.md
-pythonsources = ../python/*.py ../python/Makefile ../python/csaccess_py.c ../python/csaccess.i 
-sources = $(libsources) $(demosources) $(pythonsources)
-distfile = csaccess.tar.gz
-
-.PHONY: dist
-dist: $(distfile)
-
-# readme.html
-
-$(distfile): $(sources) ../doxygen-cfg.txt ../README.md ../LICENCE
-	tar -czf $@ $^
-	tar -tzf $@
 

build/readme_buildlib.md

@@ -4,10 +4,12 @@ Building the Library        {#buildlib}
 Default Build
 -------------
 
-The library is build from within the `./build` directory using the supplied `Makefile`.
-Simply change to the directory and run `make` to build the default version of the library.
+The library and demos can be built from the root of the CSAL installation using the master
+`makefile`. The default build will build a release version of the library and demos based
+on the platform architecture (arm or arm64). Platform architecture is detected using the
+linux `uname` command.
 
-The default version will be a linux user application release build, built into the `./lib/rel` 
+The default version will be a linux user application release build, built into the `./lib/<arch>/rel` 
 sub-directory off the main CoreSight Access Library directory. This version will not have any 
 of the optional components in the library. 
 
@@ -17,14 +19,25 @@ dynamic link library `libcsaccess.so`.
 The utility library will be built at the same time using the same parameters. This will
 appear as `libcsacc_util.a` and `libcsacc_util.so`.
 
+`make help` lists possible targets.
+
+Cross Compilation
+-----------------
+Cross compilation is supported by setting the `CROSS_COMPILE` and `ARCH` environment variables.
+
+- `CROSS_COMPILE` : Name prefix for gcc compiler in use. Compiler invoked will be `<CROSS_COMPILE>gcc`.
+Not set when compiling on native platform. It is assumed that the compiler is on the PATH.
+- `ARCH`  : Target architecture - can be `arm` or `arm64`. This selects compile time defines. Assumes that the target compiler defaults to this architecture.
+
 Additional Build Options
 ------------------------
 The following options can be added the make command line:-
-- `DEBUG=1`     : This will create the debug versions of the library in the `./lib/dbg` subdirectory.
+- `DEBUG=1`     : This will create the debug versions of the library in the `./lib/<arch>/dbg` subdirectory.
 - `BAREMETAL=1` : This will create a BareMetal version of the library. Linux headers will not be used.
 
-  The library will be delivered into the `./lib/rel_bm` directory. This library is suitable for use 
-  in embedded applications not running under Linux.
+  The library will be delivered into the `./lib/<arch>/rel_bm` directory. This library is suitable for use 
+  in embedded applications not running under Linux. Default architecture is `arm`. Set the `ARCH` environment
+  variable to use `arm64`, or cross compile.
 
 - `LPAE=1`      : This will create a version of the library with long physical address types - suitable for
                   use on cores using the LPAE extensions. This defines the `LPAE` macro at compile time to 
@@ -50,4 +63,4 @@ e.g.
 
     make DEBUG=1 BAREMETAL=1
 
-will create a debug version of the Baremetal library, delivered into the `./lib/dbg_bm` directory.
+will create a debug version of the Baremetal library, delivered into the `./lib/<arch>/dbg_bm` directory.

check_for_license.py

@@ -23,6 +23,8 @@
 
 def fn_is_source(fn):
     base, ext = os.path.splitext(fn)
+    if "makefile" in base:
+        return base
     return ext in [".c", ".cpp", ".h", ".py"]
 
 

demos/makefile

@@ -1,8 +1,25 @@
-# CoreSight Access Library - Demonstration and example builds
+#############################################################################
+#  CoreSight Access Library
+#
+#  Copyright (C) ARM Limited, 2017. All rights reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at#
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+#############################################################################
 # 
 # This makefile builds the demos for the CS Access Library 
 #
-# Default builds the standard release versions, which build into a common ../bin/rel directory
+# Default builds the standard release versions, which build into a common ../bin/<arch>/rel directory
 #
 # to build debug add DEBUG=1 to the make command line
 #
@@ -12,25 +29,28 @@
 # to build the csprofile example with halting debug sampling option active (v7 cores only),
 # add DBG_HALT=1 to the command line.
 
+# setup architecture & x-compile
+include ../makefile-arch.inc
+
 # default settings
-CC=gcc
+CC=$(CROSS_COMPILE)gcc
 CFLAGS=-Wall -Werror=implicit-function-declaration -Wno-switch -fno-omit-frame-pointer
 
 # extra per example specific options
 CFLAGS_EX=
 
 # directories
-CS_LIB_DIR = ../lib/rel
-BUILD_DIR=./rel
-BIN_DIR=../bin/rel
+CS_LIB_DIR = ../lib/$(ARCH)/rel
+BUILD_DIR=./rel-$(ARCH)
+BIN_DIR=../bin/$(ARCH)/rel
 
 
 # build options
 ifeq ($(DEBUG),1)
 CFLAGS+= -O0 -DDEBUG -g
-CS_LIB_DIR = ../lib/dbg
-BUILD_DIR=./dbg
-BIN_DIR=../bin/dbg
+CS_LIB_DIR = ../lib/$(ARCH)/dbg
+BUILD_DIR=./dbg-$(ARCH)
+BIN_DIR=../bin/$(ARCH)/dbg
 else
 CFLAGS+= -O2 -g
 endif
@@ -82,7 +102,7 @@ CSLS_SRC=csls.c
 
 CSLS_OBJS=$(addprefix $(BUILD_DIR)/,$(CSLS_SRC:%.c=%.o))
 
-csls: bin_dir $(CSLS_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(BIN_DIR)/Makefile
+csls: bin_dir $(CSLS_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(BIN_DIR)/makefile
 	$(CC) -o $(BIN_DIR)/$@ $(CSLS_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a 
 
 #  **** build the tracedemo program
@@ -91,71 +111,45 @@ CSTD_SRC=   tracedemo.c \
 
 CSTD_OBJS=$(addprefix $(BUILD_DIR)/,$(CSTD_SRC:%.c=%.o))
 
-tracedemo: bin_dir $(CSTD_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/Makefile
+tracedemo: bin_dir $(CSTD_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/makefile
 	$(CC) -o $(BIN_DIR)/$@ $(CSTD_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a 
 
-
-#  **** build the topology generator utility
-TOPOGEN_SRC=topogen.c cs_demo_known_boards.c cs_topology_detect.c cs_topology_print.c
-
-topogen: $(TOPOGEN_SRC) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/Makefile
-	$(CC) $(CFLAGS) $(INCS) -o $@ $(TOPOGEN_SRC) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a
-
 #  **** build the trace_cti_stop program
 CSTDCTI_SRC=tracedemo_cti_stop.c \
 			cs_demo_known_boards.c
 
 CSTDCTI_OBJS=$(addprefix $(BUILD_DIR)/,$(CSTDCTI_SRC:%.c=%.o))
 
-trace_cti_stop: bin_dir $(CSTDCTI_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/Makefile
+trace_cti_stop: bin_dir $(CSTDCTI_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/makefile
 	$(CC) -o $(BIN_DIR)/$@ $(CSTDCTI_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a 
 
-#  **** build the traceprofile program
-CSTP_SRC=   csprofile.c tns.c \
-			cs_demo_known_boards.c
-
-CSTP_OBJS=$(addprefix $(BUILD_DIR)/,$(CSTP_SRC:%.c=%.o))
-
-# build with risky halting debug sampling options...
-ifeq ($(DBG_HALT),1)
-PROF_LIBNAME=$(LIB_NAME)_dbghlt
-PROF_CFLAGS=-DUSING_V7_DBG_HALT
-else
-PROF_LIBNAME=$(LIB_NAME)
-PROF_CFLAGS=
-endif
-
-csprofile: CFLAGS_EX=$(PROF_CFLAGS) -UNDEBUG
-csprofile: bin_dir $(CSTP_OBJS) $(CS_LIB_DIR)/lib$(PROF_LIBNAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/Makefile
-	$(CC) -o $(BIN_DIR)/$@ $(CSTP_OBJS) $(CS_LIB_DIR)/lib$(PROF_LIBNAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a -lrt -lpthread
-
 #  **** build the ETM/PTM config print demo
 CSETM_SRC=  cs_etm_config_demo.c \
 			cs_demo_known_boards.c
 
 CSETM_OBJS=$(addprefix $(BUILD_DIR)/,$(CSETM_SRC:%.c=%.o))
 
-etmdemo: bin_dir $(CSETM_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/Makefile
+etmdemo: bin_dir $(CSETM_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a $(BIN_DIR)/makefile
 	$(CC) -o $(BIN_DIR)/$@ $(CSETM_OBJS) $(CS_LIB_DIR)/lib$(LIB_NAME).a $(CS_LIB_DIR)/lib$(LIB_NAME_UTIL).a
 
 
 # copy the snapshot makefile
-$(BIN_DIR)/Makefile:
-	cp Makefile.snapshot $(BIN_DIR)/Makefile
+$(BIN_DIR)/makefile:
+	cp makefile.snapshot $(BIN_DIR)/makefile
 
 # clean all object files and libraries
 .PHONY: clean
 clean: clean_objs
 	rm -fr $(BIN_DIR)/etmdemo
 	rm -fr $(BIN_DIR)/csls
 	rm -fr $(BIN_DIR)/tracedemo
-	rm -fr $(BIN_DIR)/csprofile
+	rm -fr $(BIN_DIR)/trace_cti_stop
+	rm -fr $(BIN_DIR)/makefile
 
 .PHONY: clean_objs
 clean_objs:
 	rm -fr $(CSLS_OBJS)
 	rm -fr $(CSTD_OBJS)
-	rm -fr $(CSTP_OBJS)
 	rm -fr $(CSETM_OBJS)
 	rm -fr $(CSTDCTI_OBJS)