CSAL 3.0: add support for MEM-AP and SoC-600

README.md

@@ -1,46 +1,57 @@
 CoreSight Access Library        {#mainpage}
 ========================
 
-The __CoreSight Access Library__ provides an API which enables user code to interact directly with CoreSight trace devices on your target.  
+The __CoreSight Access Library__ (CSAL) provides an API which enables user code to interact directly with CoreSight devices on a target.
 This allows, for example, program execution trace to be captured in a production system without the need to 
-have an external debugger connected.  The saved trace can be retrieved later and loaded into a debugger for analysis.  
+have an external debugger connected.  The saved trace can be retrieved later and loaded into a debugger for analysis. CSAL can be run on application core or a management core.
 
-The library supports a number of different CoreSight components on several target boards as described in the 
-[demos `readme`](@ref demos) file described below. 
+The library supports a number of different CoreSight components,
+and has configurations for several target SoCs and boards as described in the
+[demos `readme`](@ref demos) file described below.
 
 You can modify the library and demos to support other CoreSight components and/or boards.  An example Linux application 
 (`tracedemo`) that exercises the library is provided.  As it runs, `tracedemo` creates several files on the target, 
 including the captured trace. Ready-made example capture files are provided that can be loaded into a debugger.
 
-CoreSight Trace Component Support
----------------------------------
+CoreSight Component Support
+---------------------------
 
-The following trace components are supported by the library:-
+The following trace components are supported by the library:
 
 - ETMv3.x: used in Cortex A5, A7 cores; Cortex R4, R5 cores.
 - PTMv1.x: used in Cortex A9, A15, A17 cores.
-- ETMv4.x: Used in Cortex R7 cores.
-  Used in **V8 Architecture** Cores - Cortex A57 and A53.
+- ETMv4.x: Used in Cortex R7 and later R-profile cores.
+  Used in **V8 Architecture** Cores - Cortex A and Neoverse cores.
 - CoreSight ITM.
 - CoreSight STM.
 - CoreSight ETB.
 - CoreSight TMC in buffer mode.
 - CoreSight CTI.
 - Global Timestamp Generator.
+- CoreSight MEM-AP.
 
 The library also supports access to the v7 Arch or v8 Arch debug sampling registers,
 allowing non intrusive sampling of PC, VMID and ContextID on a running core.
 
 Optional support is provided for intrusive halting mode debug support of v7 Arch debug cores.
 
+Normally, components are accessed in the local memory space.
+The library also supports accessing components through a MEM-AP device.
+
+In addition, it provides several ways to get access to physical memory:
+- directly, suitable for a bare-metal system
+- as a Linux userspace device driver, by memory-mapping /dev/mem
+- using Linux kernel features (this is experimental)
+- through a simple OS-hosted network daemon (devmemd, provided in the package), for development
+
 Installation
 ------------
 
-Library supplied as a git repository on github - [email protected]:ARM-software/CSAL.git
+CSAL is supplied as a git repository on github - [email protected]:ARM-software/CSAL.git
 
-`./source` : Contains all the library source .c files.
+`./source` : Contains all the CSAL library source .c files.
 
-`./include`: Contains the library API header include files.
+`./include`: Contains the CSAL library API header include files.
 
 `./demos`  : Contains the source and build files for the demonstration programs.
 
@@ -50,12 +61,16 @@ Library supplied as a git repository on github - [email protected]:ARM-software/CSA
 
 `./experimental` : Unmaintained and unsupported additional demos.
 
-`./doxygen-cfg.txt` : File to generate API documentation using __doxygen__.
+`./doxygen-cfg.txt` : File to generate CSAL 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.
 
+`./coresight-tools` : Self-contained Python tools for CoreSight topology discovery.
+
+`./devmemd`   : a simple network daemon to forward memory accesses, for testing during development.
+
 
 Documentation
 -------------
@@ -84,6 +99,57 @@ See [`./build/readme_buildlib.md`](@ref buildlib) for further information on bui
 
 See [`./demos/readme_demos.md`](@ref demos) for further information on running the demos.
 
+__Simple usage__:
+
+Each CoreSight component that you need to access (trace unit, funnel, sink etc.)
+should be registered with CSAL by calling `cs_device_register`:
+see the "CoreSight component and topology registration" section of the API.
+You will need to know the physical address of the component.
+This may be obtained from a vendor datasheet, or sometimes it is discoverable
+from an on-chip ROM table. See `coresight-tools/discovery.md` for more details.
+Connections between devices should also be registered with CSAL.
+
+__Accessing components via a MEM-AP__:
+
+On some SoCs, components are accessed indirectly, via a MEM-AP component,
+which acts as a gateway into a separate address space.
+CSAL supports indirect access via MEM-AP when built with the `CSAL_MEMAP` option.
+The MEM-AP device, and any other directly accessible devices, should first
+be registered in the usual way,
+then `cs_set_default_memap()` should be called to register the MEM-AP as the
+owner for new devices.
+Subsequent device registrations take place in the address space of the MEM-AP,
+and the CSAL API functions can then act on the devices as normal.
+
+Note that access via a MEM-AP makes it especially important to avoid conflicts
+between multiple debug agents, to avoid race conditions on the MEM-AP's
+transfer registers.
+Each MEM-AP component provides two independent transfer areas, the second being at offset 0x1000.
+One can be used by an external debugger while the other is used by CSAL.
+CSAL will check the settings of MEM-AP's CLAIM register, to check if it is in use
+by an external debugger, and will then set the claim bit indicating self-hosted use.
+However, note that some external debuggers do not check or set the CLAIM bits.
+When using a MEM-AP,
+we recommend finding out which half of the MEM-AP is used by the
+debugger and using the other half.
+
+__Multithreading__:
+
+CSAL's global state is not thread-safe in general.
+However, once components are registered, it should generally be safe to use them
+concurrently from different threads as long as two threads are
+not writing to (or causing side-effects in) the same component at the same time.
+For example, one thread could program a trace unit while another is
+monitoring a trace sink and a third is sampling from a PMU,
+all via the CSAL APIs.
+
+When components are accessed indirectly via a shared MEM-AP,
+access from different threads will attempt to update the MEM-AP.
+It will generally be necessary to use some form of locking
+so that updates to the MEM-AP's transfer address register and use of its
+data transfer registers are within a critical section.
+This has not currently been implemented in CSAL.
+
 __Using the Library in Python__:
 
 This experimental code is not built by default.
@@ -158,6 +224,14 @@ Version 2.3
 - makefile updates for x-compile and master makefile in project root dir.
 - moved some code to 'experimental' directory - demos that are not maintained / supported. 
 
+Version 3.0
+-----------
+- Added support for CoreSight SoC-600 components
+- Added support for MEM-AP
+- The API now uses types 'uint32_t' and 'uint64_t' for types representing target registers
+- Minor portability and languge conformance improvements
+- Added support for network connection (devmemd) - a development aid, not intended for production
+
 ------------------------------------
 
 Licence Information

build/makefile

@@ -34,7 +34,7 @@ include ../makefile-arch.inc
 
 # default settings - allow for cross compile of library 
 CC=$(CROSS_COMPILE)gcc
-CFLAGS=-Wall -Wno-switch
+CFLAGS=-Wall -Wno-switch -Werror
 
 LIB_DIR = ../lib/$(ARCH)/rel
 LIB_DIR_BM=../lib/$(ARCH)/rel_bm
@@ -103,6 +103,7 @@ CSSRC=  cs_init_manage.c \
 		cs_cti_ect.c \
 		cs_etm.c \
 		cs_etm_v4.c \
+		cs_memap.c \
 		cs_reg_access.c \
 		cs_sw_stim.c \
 		cs_topology.c \
@@ -113,6 +114,21 @@ CSSRC=  cs_init_manage.c \
 # add in the extra for halting debug - blank if not in use 
 CSSRC+=$(CSSRC_HALT)
 
+#
+# For development use only, we can enable redirecting physical
+# memory references to a remote target over a network connection.
+#
+ifeq ($(DEVMEMD),1)
+CSSRC+=cs_stub_devmemd.c
+CFLAGS+=-DUSE_DEVMEMD
+endif
+
+#
+# Enable support for indirecting device accesses via MEM-AP.
+#
+ifeq ($(MEMAP),1)
+CFLAGS+=-DCSAL_MEMAP
+endif
 
 CSUTILSRC=	cs_trace_metadata.c \
 		cs_util_create_snapshot.c \
@@ -192,11 +208,16 @@ clean: clean_objs
 	rm -fr $(LIB_DIR)/*.so
 	rm -fr $(LIB_DIR)/*.a
 
+#
+# Clean all objects in build directories, even ones not selected by whatever
+# make options were passed to make when we ran "make clean".
+#
 .PHONY: clean_objs
 clean_objs:
-	rm -fr $(A_OBJS) $(A_DEPS)
-	rm -fr $(A_OBJS_UTIL) $(A_DEPS_UTIL)
-	rm -fr $(SO_OBJS) $(SO_DEPS)
-	rm -fr $(SO_OBJS_UTIL) $(SO_DEPS_UTIL)
-
+	#rm -fr $(A_OBJS) $(A_DEPS)
+	#rm -fr $(A_OBJS_UTIL) $(A_DEPS_UTIL)
+	#rm -fr $(SO_OBJS) $(SO_DEPS)
+	#rm -fr $(SO_OBJS_UTIL) $(SO_DEPS_UTIL)
+	rm -fr $(BUILD_DIR)/a/*.o $(BUILD_DIR)/a/*.d
+	rm -fr $(BUILD_DIR)/so/*.o $(BUILD_DIR)/so/*.d
 

build/readme_buildlib.md

@@ -57,9 +57,11 @@ The following options can be added the make command line:-
 - `NO_CHECK=1`  : This will disable additional diagnostic self checks - writes to CS registers are logged and read back.
 
 - `DBG_HALT=1`  : This will build a version of the library with the optional v7 Architecture intrusive 
-  halt mode debug functions built into the library. 
-
-  The library names will be altered to `libcsaccess_dbghlt.a` and `libcsaccess_dbghlt.so`
+  halt mode debug functions built into the library. The library names will be altered to `libcsaccess_dbghlt.a` and `libcsaccess_dbghlt.so`
+
+- `MEMAP=1`     : This will enable registering CoreSight devices behind a MEM-AP.
+
+- `USE_DEVMEMD=1` : This will compile CSAL to use the devmemd daemon on a remote target. This option is provided for development use.
 
 Options can be combined on the command line to create specific versions of the library.
 
@@ -78,3 +80,11 @@ demos   : build the demos.
 docs    : build doxygen documentation.
 clean   : clean library and demos.
 rebuild : clean and build all.
+
+Portability
+-----------
+
+The source code is portable standard C and can also be compiled as C++.
+No compiler warnings are expected.
+The code has been tested with multiple compilers.
+Please report any porting issues on the github issue tracker.

check_for_license.py

@@ -2,6 +2,8 @@
 
 """
 Check all source files (including this one) for the correct software license.
+We also allow files to be explicitly marked as having an alternate license
+by including the text "CSAL-ALTERNATE-LICENSE".
 
 Copyright (C) ARM Ltd. 2016.  All rights reserved.
 
@@ -20,27 +22,47 @@
 
 from __future__ import print_function
 
-import os
+import os, sys
+
+## Distance we need to find the license text in
+LICENSE_MAX_LINE = 20
+
+## Texts to search for, with a flag to say if it's the 'approved' license
+LICENSE_TEXT = {
+    "SPDX-License-Identifier: Apache 2.0": True,
+    "apache.org/licenses/LICENSE-2.0": True,
+    "CSAL-ALTERNATE-LICENSE": False
+}
 
 
 def fn_is_source(fn):
+    """
+    Test a filename to check that it's source code and needs a license.
+    """
     base, ext = os.path.splitext(fn)
     if "makefile" in base:
         return base
-    return ext in [".c", ".cpp", ".h", ".py"]
+    return ext in [".c", ".cpp", ".h", ".py", ".json", ".xml"]
 
 
 def fn_is_licensed(fn):
+    """
+    Check that a source file already has appropriate license text embedded in it.,
+    within the first LICENSE_MAX_LINE lines.
+    """
     found = None
     f = open(fn)
     lno = 0
     for ln in f:
         lno += 1
-        ix = ln.find("apache.org/licenses/LICENSE-2.0")
-        if ix >= 0:
-            found = lno
-            break
-        if lno > 20:
+        for ltext, is_regular in LICENSE_TEXT.items():
+            ix = ln.find(ltext)
+            if ix >= 0:
+                found = lno
+                break
+            if found is not None:
+                break
+        if lno > LICENSE_MAX_LINE:
             break
     if False:
         if found is not None:
@@ -49,15 +71,22 @@ def fn_is_licensed(fn):
 
 
 def check_all_sources_licensed(dir):
+    """
+    Scan a directory recursively, and check that all source files embed the license text.
+    """
     n_files = 0
+    n_unlicensed = 0
     for root, dirs, files in os.walk(dir):
         for f in files:
             fn = os.path.join(root, f)   
             if fn_is_source(fn):
                 n_files += 1
                 if not fn_is_licensed(fn):
+                    n_unlicensed += 1
                     print("%s: not licensed" % fn)
+    return n_unlicensed
 
 
-check_all_sources_licensed(os.path.dirname(os.path.realpath(__file__)))
+if __name__ == "__main__":
+    sys.exit(check_all_sources_licensed(os.path.dirname(os.path.realpath(__file__))) > 0)
 

coresight-tools/cskern/cskern.c

@@ -2,6 +2,8 @@
  * Minimal /dev/csmem for direct userspace access to physical memory.
  *
  * Adapted from linux/drivers/char/mem.c
+ *
+ * For the license check: CSAL-ALTERNATE-LICENSE
  */
 
 #include <linux/init.h>