{"id":28710834,"url":"https://github.com/arm-software/csal","last_synced_at":"2025-06-14T21:08:23.676Z","repository":{"id":37883417,"uuid":"76446960","full_name":"ARM-software/CSAL","owner":"ARM-software","description":"Coresight Access Library","archived":false,"fork":false,"pushed_at":"2025-05-06T07:51:22.000Z","size":1403,"stargazers_count":122,"open_issues_count":10,"forks_count":49,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-06T08:50:19.493Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARM-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-12-14T09:55:31.000Z","updated_at":"2025-05-06T07:51:26.000Z","dependencies_parsed_at":"2024-01-10T16:11:13.683Z","dependency_job_id":"71299367-9b93-44e6-b98b-c8f2f4a6eb88","html_url":"https://github.com/ARM-software/CSAL","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ARM-software/CSAL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2FCSAL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2FCSAL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2FCSAL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2FCSAL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARM-software","download_url":"https://codeload.github.com/ARM-software/CSAL/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2FCSAL/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259884525,"owners_count":22926446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-14T21:08:22.142Z","updated_at":"2025-06-14T21:08:23.665Z","avatar_url":"https://github.com/ARM-software.png","language":"C","readme":"CoreSight Access Library        {#mainpage}\n========================\n\nThe __CoreSight Access Library__ (CSAL) provides an API which enables user code to interact directly with CoreSight devices on a target.\nThis allows, for example, program execution trace to be captured in a production system without the need to \nhave 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.\n\nThe library supports a number of different CoreSight components,\nand has configurations for several target SoCs and boards as described in the\n[demos `readme`](@ref demos) file described below.\n  \nYou can modify the library and demos to support other CoreSight components and/or boards.  An example Linux application \n(`tracedemo`) that exercises the library is provided.  As it runs, `tracedemo` creates several files on the target, \nincluding the captured trace. Ready-made example capture files are provided that can be loaded into a debugger.\n\nCoreSight Component Support\n---------------------------\n\nThe following trace components are supported by the library:\n\n- ETMv3.x: used in Cortex A5, A7 cores; Cortex R4, R5 cores.\n- PTMv1.x: used in Cortex A9, A15, A17 cores.\n- ETMv4.x: Used in Cortex R7 and later R-profile and M-profile cores.\n  Used in **V8 Architecture** Cores - Cortex A and Neoverse cores.\n- ETE: Used in v9 A-profile cores.\n- CoreSight ITM.\n- CoreSight STM.\n- CoreSight ETB.\n- CoreSight TMC in buffer mode.\n- CoreSight CTI.\n- Global Timestamp Generator.\n- CoreSight MEM-AP.\n- CoreSight ELA.\n\nThe library also supports access to the v7 Arch or v8 Arch debug sampling registers,\nallowing non intrusive sampling of PC, VMID and ContextID on a running core.\n\nOptional support is provided for intrusive halting mode debug support of v7/v8 Arch debug cores.\n\nNormally, components are accessed in the local memory space.\nThe library also supports accessing components through a MEM-AP device.\n\nIn addition, it provides several ways to get access to physical memory:\n- directly, suitable for a bare-metal system\n- as a Linux userspace device driver, by memory-mapping /dev/mem\n- using Linux kernel features (this is experimental)\n- through a simple OS-hosted network daemon (devmemd, provided in the package), for development\n\nInstallation\n------------\n\nCSAL is supplied as a git repository on github - git@github.com:ARM-software/CSAL.git\n\n`./source` : Contains all the CSAL library source .c files.\n\n`./include`: Contains the CSAL library API header include files.\n\n`./demos`  : Contains the source and build files for the demonstration programs.\n\n`./build`  : The main library build `Makefile`. Change to this directory to build the library.\n\n`./python` : Build and source files to make a python module to interface to the library. (unmaintained)\n\n`./experimental` : Unmaintained and unsupported additional demos.\n\n`./doxygen-cfg.txt` : File to generate CSAL API documentation using __doxygen__.\n\n`./README.md` : This readme text file - which is also processed by __doxygen__.\n\n`./makefile`  : master makefile - `make help` for list of targets.\n\n`./coresight-tools` : Self-contained Python tools for CoreSight topology discovery.\n\n`./devmemd`   : a simple network daemon to forward memory accesses, for testing during development.\n\n\nDocumentation\n-------------\n\nAPI Documentation is provided inline in the source header files, which use the __doxygen__ standard mark-up.\nRun `doxygen` on the `./doxygen-cfg.txt` file located in the library main directory.\n\n    doxygen ./doxygen-cfg.txt\n\nThis will produce the documentation in the `./doc/html` directory. The doxygen configuration also includes\nthe `readme*.md` files as part of the documentation.\n\nUsage\n-----\n\n__Building the Library and Demos__:\n\nRun `make` from the root of the installation. This will build the standard version of the library,\nand deliver the library into the `./lib/\u003carch\u003e/rel` directory. The demonstration programs will be\nbuilt and linked to the library, delivered into the `./bin/\u003carch\u003e/rel` directory. \n\nTo use the library in a program include the file `csaccess.h` from the `./include` directory and\nlink to the built library. \n\nSee [`./build/readme_buildlib.md`](@ref buildlib) for further information on building the library.\n\nSee [`./demos/readme_demos.md`](@ref demos) for further information on running the demos.\n\n__Simple usage__:\n\nEach CoreSight component that you need to access (trace unit, funnel, sink etc.)\nshould be registered with CSAL by calling `cs_device_register`:\nsee the \"CoreSight component and topology registration\" section of the API.\nYou will need to know the physical address of the component.\nThis may be obtained from a vendor datasheet, or sometimes it is discoverable\nfrom an on-chip ROM table. See `coresight-tools/discovery.md` for more details.\nConnections between devices should also be registered with CSAL.\n\n__Accessing components via a MEM-AP__:\n\nOn some SoCs, components are accessed indirectly, via a MEM-AP component,\nwhich acts as a gateway into a separate address space.\nCSAL supports indirect access via MEM-AP when built with the `CSAL_MEMAP` option.\nThe MEM-AP device, and any other directly accessible devices, should first\nbe registered in the usual way,\nthen `cs_set_default_memap()` should be called to register the MEM-AP as the\nowner for new devices.\nSubsequent device registrations take place in the address space of the MEM-AP,\nand the CSAL API functions can then act on the devices as normal.\n\nNote that access via a MEM-AP makes it especially important to avoid conflicts\nbetween multiple debug agents, to avoid race conditions on the MEM-AP's\ntransfer registers.\nEach MEM-AP component provides two independent transfer areas, the second being at offset 0x1000.\nOne can be used by an external debugger while the other is used by CSAL.\nCSAL will check the settings of MEM-AP's CLAIM register, to check if it is in use\nby an external debugger, and will then set the claim bit indicating self-hosted use.\nHowever, note that some external debuggers do not check or set the CLAIM bits.\nWhen using a MEM-AP,\nwe recommend finding out which half of the MEM-AP is used by the\ndebugger and using the other half.\n\n__Multithreading__:\n\nCSAL's global state is not thread-safe in general.\nHowever, once components are registered, it should generally be safe to use them\nconcurrently from different threads as long as two threads are\nnot writing to (or causing side-effects in) the same component at the same time.\nFor example, one thread could program a trace unit while another is\nmonitoring a trace sink and a third is sampling from a PMU,\nall via the CSAL APIs.\n\nWhen components are accessed indirectly via a shared MEM-AP,\naccess from different threads will attempt to update the MEM-AP.\nIt will generally be necessary to use some form of locking\nso that updates to the MEM-AP's transfer address register and use of its\ndata transfer registers are within a critical section.\nThis has not currently been implemented in CSAL.\n\n__Using the Library in Python__:\n\nThis experimental code is not built by default.\nThe ./python directory contains source and makefiles to generate a python module to allow\nuse of the library. \n\nSee [`./build/readme_python.md`](@ref python) for further information.\n\n------------------------------------\n\nVersion and Modification Information\n====================================\n\nVersion 1.000\n-------------\n\nInitial Library Release.\n\nVersion 2.000\n-------------\n\nUpdates to APIs:-\n- Added in `cs_library_version()` to management API.\n- Added `cs_device_write_masked()`, `cs_device_wait()` and `cs_device_set_wait_repeats()` to the \n  register access API.\n- Added `cs_cti_set_active_channel()`, `cs_cti_clear_active_channel()` and `cs_cti_clear_all_active_channels()`\n  to the Cross Trigger Low level API.\n- Added `cs_trace_enable_cycle_accurate()` to Trace Source API. \n- _Functionality change:_ Function `cs_trace_enable_timestamps()` altered - this will no longer enable cycle accurate \n  tracing at the same time as timestamps are enabled.\n- Added in support for ETMv4. New ETMv4 structures added with ETMv4 supported in common API calls.\n- Generic ETM programming calls added - `cs_etm_config_init_ex()`, `cs_etm_config_get_ex()` and `cs_etm_config_put_ex()`. \n  These calls can be passed structures to any architecture ETM. \n- Added in support for V8 Architecture debug sampling. \n- _API change_: Function `cs_etm_static_config_init()` deprecated. Not useful in external API.\n  \nGeneral changes:-\n- Source file and directory re-structuring for improved maintenance.\n- Examples extended for additional board support. \n\n\nVersion 2.001\n-------------\n\nUpdates to APIs:-\n- STM support updated. Swstim API enhanced to differentiate between ITM / STM common fns and STM only.\n  STM now has dedicated write function targeting extended stim ports.\n- _API change_: Function `cs_stm_enable_trigger()` changed to `cs_trace_swstim_enable_trigger()`.\n  Function `cs_trace_get_sw_stim_count()` changed to `cs_trace_swstim_get_port_count()`.\n- _Functionality change:_ `cs_trace_enable()` on a STM or ITM device will no longer automatically\n  enable all stimulus ports and set the sync frequency. These operations must now be done using\n  specific API calls. This is to prevent the enable function from over-writing and user set configuration.  \n- CoreSight Access Utility library created. This provides the board registration and detection framework\n  previously built into the demo code. Also contains the trace extraction and snapshot creation code \n  to allow trace to be imported into DS-5 - format used compatible with DS-5 5.21.  Separation of this code \n  into an auxiliary library allows easier use in custom implementations. \n  Demo build modified to use this aux library. Know board configurations moved into separate file.\n- Juno (v8 board) configuration added to known boards in the demos area.\n\n\nVersion 2.002\n-------------\nUpdates to APIs:-\n- CoreSight Timestamp (TS) Generator API added.\n- `cs_trace_enable_timestamps()` updated to enable TS generation if passed a TS generator type object.\n- Updated topology detection to recognise an Embedded Logic Analyser type component.\n- Updated documentation for running Juno examples an shipping scripts to set up the platform.\n\nVersion 2.3\n-------------\n- Transfer to github project\n- makefile updates for x-compile and master makefile in project root dir.\n- moved some code to 'experimental' directory - demos that are not maintained / supported. \n\nVersion 3.0\n-----------\n- Added support for CoreSight SoC-600 components\n- Added support for MEM-AP\n- The API now uses types 'uint32_t' and 'uint64_t' for types representing target registers\n- Minor portability and languge conformance improvements\n- Added support for network connection (devmemd) - a development aid, not intended for production\n\nVersion 3.1\n-----------\n- Added support for CoreSight ELA\n\nVersion 3.2\n-----------\n- Portability and efficiency fixes\n- Increased reported version number from 2.3 to 3.2\n\nFuture changes\n--------------\nIt is unlikely that CSAL will see major development, but it may be improved in areas including:\n\n- Updates for new releases of CoreSight IP\n- Reduction of code path lengths on register access (e.g. automatic unlock-on-write may become optional)\n- Support for additional boards and SoCs in the demonstration code\n\n\n------------------------------------\n\nLicence Information\n===================\n\n*Copyright (C) ARM Limited, 2014-2024. All rights reserved.*\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at:\n \nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farm-software%2Fcsal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farm-software%2Fcsal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farm-software%2Fcsal/lists"}