From patchwork Mon Mar 10 15:04:55 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mario Fleischmann X-Patchwork-Id: 14010297 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id D49BAC282EC for ; Mon, 10 Mar 2025 15:18:15 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trenq-0002Lf-JW; Mon, 10 Mar 2025 11:12:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tren3-00025F-2v for qemu-devel@nongnu.org; Mon, 10 Mar 2025 11:11:37 -0400 Received: from smtp1.lauterbach.com ([62.154.241.196]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tremu-0007fN-OG for qemu-devel@nongnu.org; Mon, 10 Mar 2025 11:11:36 -0400 Received: (qmail 30619 invoked by uid 484); 10 Mar 2025 15:11:09 -0000 X-Qmail-Scanner-Diagnostics: from 10.2.13.100 by smtp1.lauterbach.com (envelope-from , uid 484) with qmail-scanner-2.11 (mhr: 1.0. clamdscan: 0.99/21437. spamassassin: 3.4.0. Clear:RC:1(10.2.13.100):. Processed in 0.28661 secs); 10 Mar 2025 15:11:09 -0000 Received: from unknown (HELO mflpc1.LTB.LAN) (Authenticated_SSL:mfleischmann@[10.2.13.100]) (envelope-sender ) by smtp1.lauterbach.com (qmail-ldap-1.03) with TLS_AES_256_GCM_SHA384 encrypted SMTP for ; 10 Mar 2025 15:11:08 -0000 From: Mario Fleischmann To: qemu-devel@nongnu.org Cc: alex.bennee@linaro.org, philmd@linaro.org, armbru@redhat.com, christian.boenig@lauterbach.com, Mario Fleischmann Subject: [PATCH 01/16] mcd: Introduce Multi-Core Debug (MCD) API Date: Mon, 10 Mar 2025 16:04:55 +0100 Message-Id: <20250310150510.200607-2-mario.fleischmann@lauterbach.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250310150510.200607-1-mario.fleischmann@lauterbach.com> References: <20250310150510.200607-1-mario.fleischmann@lauterbach.com> MIME-Version: 1.0 X-Qmail-Scanner-2.11: added fake Content-Type header Received-SPF: pass client-ip=62.154.241.196; envelope-from=mario.fleischmann@lauterbach.com; helo=smtp1.lauterbach.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Formatting changes to mcd_api.h to compily with QEMU's coding style guidelines: * limit line width to 80 * convert Doxygen to kernel-doc comments * avoid architecture specific defines The original MCD API version can be found at: https://repo.lauterbach.com/sprint_mcd_api_v1_0.zip Signed-off-by: Mario Fleischmann --- MAINTAINERS | 6 + docs/interop/index.rst | 1 + docs/interop/mcd.rst | 44 + mcd/mcd_api.h | 3963 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 4014 insertions(+) create mode 100644 docs/interop/mcd.rst create mode 100644 mcd/mcd_api.h diff --git a/MAINTAINERS b/MAINTAINERS index 618d75f087..448fb55a09 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3101,6 +3101,12 @@ F: scripts/feature_to_c.py F: scripts/probe-gdb-support.py T: git https://gitlab.com/stsquad/qemu gdbstub/next +MCD +M: Mario Fleischmann +S: Maintained +F: mcd/* +F: docs/interop/mcd.rst + Memory API M: Paolo Bonzini M: Peter Xu diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 999e44eae1..3644b8efb2 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -14,6 +14,7 @@ are useful for making QEMU interoperate with other software. dbus-vmstate dbus-display live-block-operations + mcd nbd parallels prl-xml diff --git a/docs/interop/mcd.rst b/docs/interop/mcd.rst new file mode 100644 index 0000000000..9587cfb010 --- /dev/null +++ b/docs/interop/mcd.rst @@ -0,0 +1,44 @@ +.. + Copyright (c) 2025 Lauterbach GmbH + SPDX-License-Identifier: GPL-2.0-or-later + + +========================== +Multi-Core Debug (MCD) API +========================== + +The Multi-Core Debug (MCD) API is a debug interface which is commonly provided +by emulators alongside other interfaces such as GDB and is specifically designed +for machine-level debugging. + +For instance, to allow physical memory access through the GDB interface, QEMU +introduced a custom maintenance packet, as explained in :doc:`/system/gdb`. +With MCD, multiple memory spaces can be made available, which can be accessed +from a given CPU. In addition to ``MCD_MEM_SPACE_IS_REGISTERS`` and +``MCD_MEM_SPACE_IS_LOGICAL``, the types also include +``MCD_MEM_SPACE_IS_PHYSICAL``. Each memory and register accessed is initiated +through a transaction. Depending on the memory space identifier in the address, +the transaction accesses registers, logical memory (with MMU), or physical +memory. + +Operations like accessing memory or registers, and controlling the execution +flow, are all performed with respect to an open core connection. As the +following diagram shows, cores are part of a hierarchical system structure which +can be directly mapped to QEMU's options: + +.. code-block:: bash + + $ qemu-system-* -machine * -cpu * -smp * (...) + +The resulting system can be visualized as follows:: + + +----------------+ +----------+ +------+ + | System | 1 1 | Device | 1 -smp | Core | + | |------| |-----------| | + | qemu-system-* | | -machine | | -cpu | + +----------------+ +----------+ +------+ + +API Reference +------------- + +.. kernel-doc:: mcd/mcd_api.h diff --git a/mcd/mcd_api.h b/mcd/mcd_api.h new file mode 100644 index 0000000000..8c893538f8 --- /dev/null +++ b/mcd/mcd_api.h @@ -0,0 +1,3963 @@ +/* + * Copyright (c) 2008, ARM Ltd., Infineon Technologies, NXP Semiconductors, + * Lauterbach, STMicroelectronics and TIMA Laboratory. + * All rights reserved. + * + * PREAMBLE + * + * The MCD API (Multi-Core Debug) has been designed as an interface between + * software development tools and simulated or real systems with multi-core + * SoCs. The target is to allow consistent software tooling throughout the + * whole SoC development flow. + * The MCD API (the "SOFTWARE") has been developed jointly by ARM Ltd., + * Infineon Technologies, NXP Semiconductors, Lauterbach, + * STMicroelectronics and TIMA Laboratory as part of the SPRINT project + * (www.sprint-project.net). + * The SPRINT project has been funded by the European Commission. + * + * LICENSE + * + * Any redistribution and use of the SOFTWARE in source and binary forms, + * with or without modification constitutes the full acceptance of the + * following disclaimer as well as of the license herein and is permitted + * provided that the following conditions are met: + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the disclaimer detailed below. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the disclaimer detailed below in the + * documentation and/or other materials provided with the distribution. + * - Neither the name of its copyright holders nor the names of its + * contributors may be used to endorse or promote products derived from the + * Software without specific prior written permission. + * - Modification of any or all of the source code, documentation and other + * materials provided under this license are subject to acknowledgement of + * the modification(s) by including a prominent notice on the modification(s) + * stating the change(s) to the file(s), identifying the date of such change + * and stating the name of the publisher of any such modification(s). + * + * DISCLAIMER OF WARRANTY AND LIABILITY + * + * THE SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT AND FITNESS FOR A + * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER + * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE, + * MISREPRESENTATION OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * VERSION HISTORY + * + * 1.0 "SPRINT Release" : SPRINT reference version + * + * 1.1 "Lauterbach Release" : + * - forces all boolean types to 8-bit on Linux and Mac-OS-X, + * but 32-bit on all other OS forces 32-bit enumeration types + * - additional memory spaces MCD_MEM_SPACE_IS_PHYSICAL, + * MCD_MEM_SPACE_IS_LOGICAL, MCD_MEM_SPACE_IS_AUX + * - changed type of 2nd argument of mcd_qry_input_handle_f from "int" to + * "uint32_t" + * - changed type of element "data" of of mcd_tx_st from "unsigned char" to + * "uint8_t" + * - specifying the calling convention for MS Windows (x86) to __cdecl + * + * 1.2 "QEMU Release" : + * - changes formatting to accommodate QEMU's coding style guidelines + * - includes qemu/osdep.h instead of mcd_types.h + */ + + +/** + * DOC: Using the MCD API + * + * The MCD API has been captured in a single header file and all API users have + * to include this header file in their source code. The following has to be + * noted when including this header file: + * + * - The MCD API extensively utilizes standard fixed size integer types as + * defined by ISO. These types can be found in the system library header named + * . In case this file is not provided with the used platform and/or + * build environment, suitable definitions for the required types need to be + * created. In most cases it should be possible to find definitions of these + * platform-specific types on the internet. + * + * The MCD API is composed of two distinct parts: + * + * - An API in order to allow tools to access debug targets in a uniform way + * (ToolsAPI). + * - An API in order to allow the MCD framework to access target components in a + * standard way (TargetAPI). + * + * The following naming conventions have been introduced for the definition of + * the various data structures and function calls of the MCD API: + * + * - All data structures begin with the prefix 'mcd'. This stands for + * "Multi-Core Debugging". + * - All data structures used by the API functions that are C Enumerations end + * in the suffix '_et'. This stands for "Enumeration Type". With version 1.1 + * of the API all enumeration types are defined as 32-bit unsigned integers. + * - All data structures used by the API functions that are C Structures end in + * the suffix '_st'. This stands for "Structure Type". + * - All API function names begin with the prefix 'mcd'. This stands for + * "Multi-Core Debugging". + * - All API function names end in the suffix '_f'. This stands for "Function". + * + * In addition to this, the following convention is assumed to be applied to all + * implementations: + * + * - All strings are terminated by a zero character. + * - All member of a structure must be aligned to their size E.g. members must + * of type uint64_t must be aligned to an offset divisible by 8. + * - The calling convention for implementations on MS Windows for x86 CPUs is + * __cdecl + * + * If MCD API extensions are needed, it is strongly recommended to add them + * outside of this header file for compatibility reasons. If this is not + * possible it is mandatory to modify the MCD_API_VER_AUTHOR to a different + * string than "SPRINT Release". New versions of the "SPRINT Release" may only + * be created by the copyright holders listed in the license text. + */ + + +/* + * mcd_api.h + * The Multi-Core Debug (MCD) API defined as a part of the SPRINT Project + * This is the definition of the Multi-Core Debug API as defined by SPRINT. + */ + + +#ifndef MCD_API_H +#define MCD_API_H + +#include "qemu/osdep.h" + + +/** + * DOC: Definitions of Constant + * + * This is a list of constant values as defined for the utilization by data + * structures of the MCD API. + */ + + +/** + * define MCD_API_VER_MAJOR - Major revision number of this API. + */ +#define MCD_API_VER_MAJOR 1 + +/** + * define MCD_API_VER_MINOR - Minor revision number of this API. + * + * Version 1.2 only introduced formatting changes + */ +#define MCD_API_VER_MINOR 1 + +/** + * define MCD_API_VER_AUTHOR - Author of this API + * + * Version 1.2 introduces MCD into QEMU + * Version 1.1 extends 1.0 "SPRINT Release" by fixed types + * Version 1.0 "SPRINT Release" is the SPRINT reference version + */ +#define MCD_API_VER_AUTHOR "QEMU Release" + +/** + * define MCD_API_VER_BUILD - Build revision number of this API. + * + * SVN revision not applicable to QEMU. + */ +#define MCD_API_VER_BUILD 0 + +/** + * define MCD_HOSTNAME_LEN - Maximum length of the host's name which runs the + * debug server (incl. terminating zero). + */ +#define MCD_HOSTNAME_LEN 64 /* Maximum length of the host's name */ + +/** + * define MCD_REG_NAME_LEN - Maximum length of a register name + * (incl. terminating zero). + */ +#define MCD_REG_NAME_LEN 32 + +/** + * define MCD_MEM_SPACE_NAME_LEN - Maximum length of a memory space name + * (incl. terminating zero). + */ +#define MCD_MEM_SPACE_NAME_LEN 32 + +/** + * define MCD_MEM_BLOCK_NAME_LEN - Maximum length of a memory block name + * (incl. terminating zero). + */ +#define MCD_MEM_BLOCK_NAME_LEN 32 + +/** + * define MCD_MEM_BLOCK_NOPARENT - Parent ID to be assigned to a memory block + * at root level. + */ +#define MCD_MEM_BLOCK_NOPARENT 0 + +/** + * define MCD_MEM_AUSIZE_NUM - Maximum number of supported Addressable Unit + * sizes. + */ +#define MCD_MEM_AUSIZE_NUM 8 + +/** + * define MCD_INFO_STR_LEN - Maximum length of an info string + * (incl. terminating zero). + */ +#define MCD_INFO_STR_LEN 256 + +/** + * define MCD_KEY_LEN - Maximum length of keys (incl. terminating zero). + */ +#define MCD_KEY_LEN 64 + +/** + * define MCD_UNIQUE_NAME_LEN - Maximum length of a unique name string + * (incl. terminating zero). + */ +#define MCD_UNIQUE_NAME_LEN 64 + +/** + * define MCD_MAX_TRIGS - Maximum number of triggers supported per core. + */ +#define MCD_MAX_TRIGS 32 + +/** + * define MCD_API_IMP_VENDOR_LEN - Maximum name length of the API implementation + * vendor (incl. terminating zero). + */ +#define MCD_API_IMP_VENDOR_LEN 32 + +/** + * define MCD_CHL_NUM_MAX - Maximum number of supported communication channels. + */ +#define MCD_CHL_NUM_MAX 32 + +/** + * define MCD_CHL_LOWEST_PRIORITY - Lowest channel priority + * [Range: 0 (highest) to 15 (lowest)]. + */ +#define MCD_CHL_LOWEST_PRIORITY 15 + +/** + * define MCD_TX_NUM_MAX - Maximum number of transactions supported per + * transaction list. + */ +#define MCD_TX_NUM_MAX 64 + +/** + * define MCD_GUARANTEED_MIN_PAYLOAD - Minimum payload guaranteed per + * transaction list (in bytes). + */ +#define MCD_GUARANTEED_MIN_PAYLOAD 16384 + +/** + * define MCD_CORE_MODE_NAME_LEN - Maximum name length of a core mode, e.g. + * user, supervisor, secure + * (incl. terminating zero). + */ +#define MCD_CORE_MODE_NAME_LEN 32 + + +/** + * DOC: Definition of Enumerations + * + * This is a list of enumeration values as defined for the utilization + * by data structures of the MCD API. + */ + + +/** + * typedef mcd_return_et - Enumeration type defining the action a calling + * function has to take after an MCD API function call. + * + * The calling function has to evaluate the return value of an MCD API function + * call in order to check its success. If the function returned with an error an + * appropriate action has to be taken as defined by the return value. All MCD + * API functions return a value of type mcd_return_et. The calling function has + * to decide the further proceeding based on it. + * + * A few return codes have been reserved for future API use and must not be + * used. Any further value can be used for customized actions. All of these user + * defined actions need to have values between %MCD_RET_ACT_CUSTOM_LO and + * %MCD_RET_ACT_CUSTOM_HI. + * + * * %MCD_RET_ACT_NONE - No special action required. + * * %MCD_RET_ACT_AGAIN - Try to call the function again. + * * %MCD_RET_ACT_HANDLE_EVENT - Handle the event or events. + * * %MCD_RET_ACT_HANDLE_ERROR - Handle the error. + * * %MCD_RET_ACT_RESERVED_LO - Begin Range: Action reserved for future API use. + * * %MCD_RET_ACT_RESERVED_HI - End Range: Action reserved for future API use. + * * %MCD_RET_ACT_CUSTOM_LO - Begin Range: For user defined actions. + * * %MCD_RET_ACT_CUSTOM_HI - End Range: For user defined actions. + */ +typedef uint32_t mcd_return_et; +enum { + MCD_RET_ACT_NONE = 0x00000000, + MCD_RET_ACT_AGAIN = 0x00000001, + MCD_RET_ACT_HANDLE_EVENT = 0x00000002, + MCD_RET_ACT_HANDLE_ERROR = 0x00000003, + MCD_RET_ACT_RESERVED_LO = 0x00000004, + MCD_RET_ACT_RESERVED_HI = 0x00008000, + MCD_RET_ACT_CUSTOM_LO = 0x00010000, + MCD_RET_ACT_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_error_code_et - Enumeration type defining the detailed error + * codes that can be returned by an MCD API function + * call. + * + * The calling function has to evaluate the return value of an MCD API function + * call in order to check its success. If the function returned with an error an + * appropriate action has to be taken as defined by the return value. All MCD + * API functions return a value of type mcd_return_et. If the returned value + * indicates an error, the user has to retrieve the detailed information on the + * occurred error by calling mcd_qry_error_info_f(). The following enumeration + * is part of this information and describes the detailed error codes. + * + * The enumeration's values can be subdivided into the following categories: + * + * - GENERAL (0x0000-0x0FFF) : These errors can be returned by any + * MCD API function call. + * - API_SPECIFIC (0x1000-0x10000000) : These errors are specific to + * certain MCD API function calls. Some of them may be valid for multiple MCD + * API function calls. + * - CUSTOM (0x10000000-0x7FFFFFFF) : These error codes can be defined by + * the user and carry user defined semantics. + * + * * %MCD_ERR_NONE - No error. + * * %MCD_ERR_FN_UNIMPLEMENTED - Called function is not implemented. + * * %MCD_ERR_USAGE - MCD API not correctly used. + * * %MCD_ERR_PARAM - Passed invalid parameter. + * * %MCD_ERR_CONNECTION - Server connection error. + * * %MCD_ERR_TIMED_OUT - Function call timed out. + * * %MCD_ERR_GENERAL - General error. + * * %MCD_ERR_RESULT_TOO_LONG - String to return is longer than the provided + * character array. + * * %MCD_ERR_COULD_NOT_START_SERVER - Could not start server. + * * %MCD_ERR_SERVER_LOCKED - Server is locked. + * * %MCD_ERR_NO_MEM_SPACES - No memory spaces defined. + * * %MCD_ERR_NO_MEM_BLOCKS - No memory blocks defined for the requested memory + * space. + * * %MCD_ERR_MEM_SPACE_ID - No memory space with requested ID exists. + * * %MCD_ERR_NO_REG_GROUPS - No register groups defined. + * * %MCD_ERR_REG_GROUP_ID - No register group with requested ID exists. + * * %MCD_ERR_REG_NOT_COMPOUND - Register is not a compound register. + * * %MCD_ERR_OVERLAYS - Error retrieving overlay information. + * * %MCD_ERR_DEVICE_ACCESS - Cannot access device (power-down, reset active, + * etc.). + * * %MCD_ERR_DEVICE_LOCKED - Device is locked. + * * %MCD_ERR_TXLIST_READ - Read transaction of transaction list has failed. + * * %MCD_ERR_TXLIST_WRITE - Write transaction of transaction list has failed. + * * %MCD_ERR_TXLIST_TX - Other error (no R/W failure) for a transaction of the + * transaction list. + * * %MCD_ERR_CHL_TYPE_NOT_SUPPORTED - Requested channel type is not supported + * by the implementation. + * * %MCD_ERR_CHL_TARGET_NOT_SUPPORTED - Addressed target does not support + * communication channels. + * * %MCD_ERR_CHL_SETUP - Channel setup is invalid or contains unsupported + * attributes. + * * %MCD_ERR_CHL_MESSAGE_FAILED - Sending or receiving of the last message has + * failed. + * * %MCD_ERR_TRIG_CREATE - Trigger could not be created. + * * %MCD_ERR_TRIG_ACCESS - Error during trigger information access. + * * %MCD_ERR_CUSTOM_LO - Begin Range: For user defined errors. + * * %MCD_ERR_CUSTOM_HI - End Range: For user defined errors. + */ +typedef uint32_t mcd_error_code_et; +enum { + + MCD_ERR_NONE = 0, + + MCD_ERR_FN_UNIMPLEMENTED = 0x0100, + MCD_ERR_USAGE = 0x0101, + MCD_ERR_PARAM = 0x0102, + MCD_ERR_CONNECTION = 0x0200, + MCD_ERR_TIMED_OUT = 0x0201, + + MCD_ERR_GENERAL = 0x0F00, + + MCD_ERR_RESULT_TOO_LONG = 0x1000, + + MCD_ERR_COULD_NOT_START_SERVER = 0x1100, + MCD_ERR_SERVER_LOCKED = 0x1101, + + MCD_ERR_NO_MEM_SPACES = 0x1401, + MCD_ERR_NO_MEM_BLOCKS = 0x1402, + MCD_ERR_MEM_SPACE_ID = 0x1410, + MCD_ERR_NO_REG_GROUPS = 0x1440, + MCD_ERR_REG_GROUP_ID = 0x1441, + MCD_ERR_REG_NOT_COMPOUND = 0x1442, + + MCD_ERR_OVERLAYS = 0x1500, + + MCD_ERR_DEVICE_ACCESS = 0x1900, + MCD_ERR_DEVICE_LOCKED = 0x1901, + + MCD_ERR_TXLIST_READ = 0x2100, + MCD_ERR_TXLIST_WRITE = 0x2101, + MCD_ERR_TXLIST_TX = 0x2102, + + MCD_ERR_CHL_TYPE_NOT_SUPPORTED = 0x3100, + MCD_ERR_CHL_TARGET_NOT_SUPPORTED = 0x3101, + MCD_ERR_CHL_SETUP = 0x3102, + MCD_ERR_CHL_MESSAGE_FAILED = 0x3140, + + MCD_ERR_TRIG_CREATE = 0x3200, + MCD_ERR_TRIG_ACCESS = 0x3201, + + MCD_ERR_CUSTOM_LO = 0x10000000, + MCD_ERR_CUSTOM_HI = 0x7FFFFFFF, +}; + + +/** + * typedef mcd_error_event_et - Enumeration type defining the error events that + * can be returned by an MCD API function call. + * + * The calling function has to evaluate the return value of an MCD API function + * call in order to check its success. If the function returned with an error an + * appropriate action has to be taken as defined by the return value. All MCD + * API functions return a value of type mcd_return_et. If the returned value + * indicates an event, the user has to retrieve the detailed information on the + * occurred error by calling mcd_qry_error_info_f(). The following enumeration + * is part of this information and describes the detailed event codes. + * + * Event codes are bitwise exclusive. This allows 32 different event codes. User + * defined event codes need to have values between %MCD_ERR_EVT_CUSTOM_LO and + * %MCD_ERR_EVT_CUSTOM_HI. Reserved error event codes must not be used. + * + * * %MCD_ERR_EVT_NONE - No action required due to an event. + * * %MCD_ERR_EVT_RESET - Target has been reset. + * * %MCD_ERR_EVT_PWRDN - Target has been a powered down. + * * %MCD_ERR_EVT_HWFAILURE - There has been a target hardware failure. + * * %MCD_ERR_EVT_RESERVED_LO - Begin Range: Events reserved for future API use. + * * %MCD_ERR_EVT_RESERVED_HI - End Range: Events reserved for future API use. + * * %MCD_ERR_EVT_CUSTOM_LO - Begin Range: User defined events. + * * %MCD_ERR_EVT_CUSTOM_HI - End Range: User defined events. + */ +typedef uint32_t mcd_error_event_et; +enum { + MCD_ERR_EVT_NONE = 0x00000000, + MCD_ERR_EVT_RESET = 0x00000001, + MCD_ERR_EVT_PWRDN = 0x00000002, + MCD_ERR_EVT_HWFAILURE = 0x00000004, + MCD_ERR_EVT_RESERVED_LO = 0x00000008, + MCD_ERR_EVT_RESERVED_HI = 0x00008000, + MCD_ERR_EVT_CUSTOM_LO = 0x00010000, + MCD_ERR_EVT_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_addr_space_type_et - Enumeration type defining the type of an + * address space ID. + * + * The type of the address space ID defines the interpretation of an address + * space ID. This type refers to the addr_space_id member of mcd_addr_st which + * is used to further extend the address information. + * + * * %MCD_NOTUSED_ID - Address space ID is not used. + * * %MCD_OVERLAY_ID - Address space ID represents the memory overlay the + * address is valid in. + * * %MCD_MEMBANK_ID - Address space ID represents the memory bank the address + * is valid in. + * * %MCD_PROCESS_ID - Address space ID represents the process the address is + * valid in. + * * %MCD_HW_THREAD_ID - Address space ID represents the hardware thread the + * address is valid in. + */ +typedef uint32_t mcd_addr_space_type_et; +enum { + + MCD_NOTUSED_ID = 0, + MCD_OVERLAY_ID = 1, + MCD_MEMBANK_ID = 2, + MCD_PROCESS_ID = 3, + MCD_HW_THREAD_ID = 4, +}; + + +/** + * typedef mcd_mem_type_et - Enumeration type defining the type of a memory + * space. + * + * Different types of memory spaces are possible. This enumeration type + * describes them. The type values %MCD_MEM_SPACE_IS_REGISTERS, + * %MCD_MEM_SPACE_IS_PROGRAM, %MCD_MEM_SPACE_IS_VIRTUAL and + * %MCD_MEM_SPACE_IS_CACHE are bitwise mutually exclusive. + * %MCD_MEM_SPACE_IS_PHYSICAL or %MCD_MEM_SPACE_IS_LOGICAL should be set when + * the target contains a memory management unit (MMU) that translates memory + * addresses between core and memory. User defined memory space types need to + * have values between %MCD_MEMSPACE_CUSTOM_HI and %MCD_MEMSPACE_CUSTOM_HI. + * Reserved memory space types must not be used. + * + * * %MCD_MEM_SPACE_DEFAULT - The memory space is of none of the types below. + * * %MCD_MEM_SPACE_IS_REGISTERS - The memory space contains only registers. + * * %MCD_MEM_SPACE_IS_PROGRAM - The memory space is a program memory. + * * %MCD_MEM_SPACE_IS_VIRTUAL - The memory space is virtual (resource not + * existing in target). + * * %MCD_MEM_SPACE_IS_CACHE - The memory space is a cache. + * * %MCD_MEM_SPACE_IS_PHYSICAL - The memory space is physical memory (not + * translated by MMU). + * * %MCD_MEM_SPACE_IS_LOGICAL - The memory space is logical memory (translated + * by MMU). + * * %MCD_MEM_SPACE_RESERVED_LO - Begin Range: Reserved for future API use. + * * %MCD_MEM_SPACE_RESERVED_HI - End Range: Reserved for future API use. + * * %MCD_MEM_SPACE_CUSTOM_LO - Begin Range: User defined memory types. + * * %MCD_MEM_SPACE_CUSTOM_HI - End Range: User defined memory types. + */ +typedef uint32_t mcd_mem_type_et; +enum { + MCD_MEM_SPACE_DEFAULT = 0x00000000, + MCD_MEM_SPACE_IS_REGISTERS = 0x00000001, + MCD_MEM_SPACE_IS_PROGRAM = 0x00000002, + MCD_MEM_SPACE_IS_VIRTUAL = 0x00000004, + MCD_MEM_SPACE_IS_CACHE = 0x00000008, + MCD_MEM_SPACE_IS_PHYSICAL = 0x00000010, + MCD_MEM_SPACE_IS_LOGICAL = 0x00000020, + MCD_MEM_SPACE_RESERVED_LO = 0x00000040, + MCD_MEM_SPACE_RESERVED_HI = 0x00008000, + MCD_MEM_SPACE_CUSTOM_LO = 0x00010000, + MCD_MEM_SPACE_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_endian_et - Enumeration type defining the endianness of a memory + * space or a memory block. + * + * The endianness of a memory can be either Little Endian or Big Endian. This + * enumeration type describes the two possible values of endianness and is used + * to set the corresponding property of a memory space and a memory block + * description. If memory blocks are supported, the value of a memory block + * overrides the one for the memory space it is part of. + * + * * %MCD_ENDIAN_DEFAULT - Endianness as defined by the target architecture or + * parent module (if available). + * * %MCD_ENDIAN_LITTLE - Little Endian data representation. + * * %MCD_ENDIAN_BIG - Big Endian data representation. + */ +typedef uint32_t mcd_endian_et; +enum { + MCD_ENDIAN_DEFAULT = 0, + MCD_ENDIAN_LITTLE = 1, + MCD_ENDIAN_BIG = 2, +}; + + +/** + * typedef mcd_reg_type_et - Enumeration type defining the allowed register + * types. + * + * A register can be a simple register, a compound register or a partial + * register. This enumeration type describes the three register types. + * + * * %MCD_REG_TYPE_SIMPLE - Simple register. + * * %MCD_REG_TYPE_COMPOUND - Compound register composed more than one simple + * register. + * * %MCD_REG_TYPE_PARTIAL - Register that is part of a simple register. + */ +typedef uint32_t mcd_reg_type_et; +enum { + MCD_REG_TYPE_SIMPLE = 0, + MCD_REG_TYPE_COMPOUND = 1, + MCD_REG_TYPE_PARTIAL = 2, +}; + + +/** + * typedef mcd_trig_type_et - Enumeration type defining the type of a trigger. + * + * This enumeration type describes the possible types of triggers for the + * target. The type values are bitwise mutually exclusive and a member of type + * mcd_trig_type_et may be a combination of several of them. The type + * %MCD_TRIG_TYPE_CUSTOM refers to a custom trigger (not a custom trigger type) + * using the standard format as defined by mcd_trig_custom_st. User defined + * trigger types need to have values between %MCD_TRIG_TYPE_CUSTOM_LO and + * %MCD_TRIG_TYPE_CUSTOM_HI. + * + * * %MCD_TRIG_TYPE_UNDEFINED - Undefined trigger type. + * * %MCD_TRIG_TYPE_IP - Trigger on a changing instruction pointer. + * * %MCD_TRIG_TYPE_READ - Trigger on a read data access to a specific address + * or address range. + * * %MCD_TRIG_TYPE_WRITE - Trigger on a write data access to a specific address + * or address range. + * * %MCD_TRIG_TYPE_RW - Trigger on a read or a write data access to a specific + * address or address range. + * * %MCD_TRIG_TYPE_NOCYCLE - Trigger on core information other than an IP or + * data compare trigger. + * * %MCD_TRIG_TYPE_TRIG_BUS - Trigger on a trigger bus combination. + * * %MCD_TRIG_TYPE_COUNTER - Trigger on an elapsed trigger counter. + * * %MCD_TRIG_TYPE_CUSTOM - Custom trigger using standard format as defined by + * mcd_trig_custom_st. + * * %MCD_TRIG_TYPE_CUSTOM_LO - Begin Range: User defined trigger types. + * * %MCD_TRIG_TYPE_CUSTOM_HI - End Range: User defined trigger types. + */ +typedef uint32_t mcd_trig_type_et; +enum { + MCD_TRIG_TYPE_UNDEFINED = 0x00000000, + MCD_TRIG_TYPE_IP = 0x00000001, + MCD_TRIG_TYPE_READ = 0x00000002, + MCD_TRIG_TYPE_WRITE = 0x00000004, + MCD_TRIG_TYPE_RW = 0x00000008, + MCD_TRIG_TYPE_NOCYCLE = 0x00000010, + MCD_TRIG_TYPE_TRIG_BUS = 0x00000020, + MCD_TRIG_TYPE_COUNTER = 0x00000040, + MCD_TRIG_TYPE_CUSTOM = 0x00000080, + MCD_TRIG_TYPE_CUSTOM_LO = 0x00010000, + MCD_TRIG_TYPE_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_trig_opt_et - Enumeration type defining additional options for a + * trigger. + * + * This enumeration type describes the additionally possible options for + * triggers in a target. The type values are bitwise mutually exclusive and a + * member of type mcd_trig_opt_et may be a combination of several of them. User + * defined trigger options need to have values between %MCD_TRIG_OPT_CUSTOM_LO + * and %MCD_TRIG_OPT_CUSTOM_HI. + * + * * %MCD_TRIG_OPT_DEFAULT - Default trigger options, e.g. chosen by the + * platform. + * * %MCD_TRIG_OPT_IMPL_HARDWARE - The trigger shall be implemented by hardware. + * * %MCD_TRIG_OPT_IMPL_SOFTWARE - The trigger shall be implemented by software + * (code substitution). + * * %MCD_TRIG_OPT_OUT_OF_RANGE - The trigger is activated when a data access is + * performed outside the specified range. + * * %MCD_TRIG_OPT_DATA_IS_CONDITION - The value of a data access is part of the + * trigger condition. + * * %MCD_TRIG_OPT_DATASIZE_IS_CONDITION - The size of a data access is part of + * the trigger condition. + * * %MCD_TRIG_OPT_NOT_DATA - The data comparison done in a trigger condition is + * negated. + * * %MCD_TRIG_OPT_SIGNED_DATA - The data values are considered as signed for + * the trigger condition. This usually requires the setting of + * %MCD_TRIG_OPT_DATASIZE_IS_CONDITION. + * * %MCD_TRIG_OPT_HW_THREAD_IS_CONDITION - The hardware thread ID is part of + * the trigger condition. + * * %MCD_TRIG_OPT_NOT_HW_THREAD - The comparison of the hardware thread ID is + * negated. + * * %MCD_TRIG_OPT_SW_THREAD_IS_CONDITION - The software thread ID is part of + * the trigger condition. + * * %MCD_TRIG_OPT_NOT_SW_THREAD - The comparison of the software thread ID is + * negated. + * * %MCD_TRIG_OPT_DATA_MUST_CHANGE - The data value of the cycle must change + * the value of the target location. This applies only to triggers on write + * cycles. The data_mask field defines which bits are considered for the + * comparison. + * * %MCD_TRIG_OPT_CORE_MODE_IS_CONDITION - The core mode as defined by the + * member core_mode_mask of a mcd_trig_complex_core_st is part of the trigger + * condition. Each set bit prevents the related core mode from activating the + * trigger. + * * %MCD_TRIG_OPT_STATE_IS_CONDITION - The state of the trigger set's state + * machine is part of the trigger condition. + * * %MCD_TRIG_OPT_NOT - The trigger condition is negated, i.e. action is taken + * if the whole trigger condition is NOT met. This should not be mixed up with + * %MCD_TRIG_OPT_OUT_OF_RANGE which inverts just the address range. + * * %MCD_TRIG_OPT_CUSTOM_LO - Begin Range: User defined trigger options. + * * %MCD_TRIG_OPT_CUSTOM_HI - End Range: User defined trigger options. + */ +typedef uint32_t mcd_trig_opt_et; +enum { + MCD_TRIG_OPT_DEFAULT = 0x00000000, + MCD_TRIG_OPT_IMPL_HARDWARE = 0x00000001, + MCD_TRIG_OPT_IMPL_SOFTWARE = 0x00000002, + MCD_TRIG_OPT_OUT_OF_RANGE = 0x00000004, + MCD_TRIG_OPT_DATA_IS_CONDITION = 0x00000008, + MCD_TRIG_OPT_DATASIZE_IS_CONDITION = 0x00000010, + MCD_TRIG_OPT_NOT_DATA = 0x00000020, + MCD_TRIG_OPT_SIGNED_DATA = 0x00000040, + MCD_TRIG_OPT_HW_THREAD_IS_CONDITION = 0x00000080, + MCD_TRIG_OPT_NOT_HW_THREAD = 0x00000100, + MCD_TRIG_OPT_SW_THREAD_IS_CONDITION = 0x00000200, + MCD_TRIG_OPT_NOT_SW_THREAD = 0x00000400, + MCD_TRIG_OPT_DATA_MUST_CHANGE = 0x00000800, + MCD_TRIG_OPT_CORE_MODE_IS_CONDITION = 0x00020000, + MCD_TRIG_OPT_STATE_IS_CONDITION = 0x00040000, + MCD_TRIG_OPT_NOT = 0x00080000, + MCD_TRIG_OPT_CUSTOM_LO = 0x00100000, + MCD_TRIG_OPT_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_trig_action_et - Enumeration type defining the trigger action + * types. + * + * This enumeration type describes the possible actions for triggers in a + * target. The type values are bitwise mutually exclusive and a member of type + * mcd_trig_action_et may be a combination of several of them. User defined + * trigger actions need to have values between %MCD_TRIG_ACTION_CUSTOM_LO and + * %MCD_TRIG_ACTION_CUSTOM_HI. + * + * * %MCD_TRIG_ACTION_DEFAULT - No action has to be taken except from setting + * the trigger to be captured. + * * %MCD_TRIG_ACTION_DBG_DEBUG - Stop this core and bring it into debug mode. + * * %MCD_TRIG_ACTION_DBG_GLOBAL - Stop all cores and bring them into debug + * mode. + * * %MCD_TRIG_ACTION_DBG_MONITOR - Issue an exception (monitor interrupt) on + * this core in order to execute the monitor code. + * * %MCD_TRIG_ACTION_TRIG_BUS_EVENT - Signal the according event on the trigger + * bus (for the duration of one core cycle). The corresponding bitmask is + * specified by the member action_param of the used trigger data structure. + * * %MCD_TRIG_ACTION_TRIG_BUS_SET - Set bits on the trigger bus. The + * corresponding bitmask is specified by the member action_param of the used + * trigger data structure. + * * %MCD_TRIG_ACTION_TRIG_BUS_CLEAR - Clear bits on the trigger bus. The + * corresponding bitmask is specified by the member action_param of the used + * trigger data structure. + * * %MCD_TRIG_ACTION_TRACE_QUALIFY - Trace this cycle. + * * %MCD_TRIG_ACTION_TRACE_QUALIFY_PROGRAM - Trace this cycle, affects program + * trace only. + * * %MCD_TRIG_ACTION_TRACE_QUALIFY_DATA - Trace this cycle, affects data trace + * only. + * * %MCD_TRIG_ACTION_TRACE_START - Start tracing. + * * %MCD_TRIG_ACTION_TRACE_STOP - Stop tracing. + * * %MCD_TRIG_ACTION_TRACE_TRIGGER - Trigger trace unit. + * * %MCD_TRIG_ACTION_ANA_START_PERFM - Start performance analysis or profiling. + * * %MCD_TRIG_ACTION_ANA_STOP_PERFM - Stop performance analysis or profiling. + * * %MCD_TRIG_ACTION_STATE_CHANGE - Set the trigger set's state machine to a + * new state. The corresponding state is specified by the member action_param + * of the used trigger data structure. + * * %MCD_TRIG_ACTION_COUNT_QUALIFY - Increment the counter specified by the + * member action_param of the used trigger data structure. + * * %MCD_TRIG_ACTION_COUNT_START - Start the counter specified by the member + * action_param of the used trigger data structure. + * * %MCD_TRIG_ACTION_COUNT_STOP - Stop the counter specified by the member + * action_param of the used trigger data structure. + * * %MCD_TRIG_ACTION_COUNT_RESTART - Restart the counter specified by the + * member action_param of the used trigger data structure. + * * %MCD_TRIG_ACTION_CUSTOM_LO - Begin Range: User defined trigger actions. + * * %MCD_TRIG_ACTION_CUSTOM_HI - End Range: User defined trigger actions. + */ +typedef uint32_t mcd_trig_action_et; +enum { + MCD_TRIG_ACTION_DEFAULT = 0x00000000, + MCD_TRIG_ACTION_DBG_DEBUG = 0x00000001, + MCD_TRIG_ACTION_DBG_GLOBAL = 0x00000002, + MCD_TRIG_ACTION_DBG_MONITOR = 0x00000004, + MCD_TRIG_ACTION_TRIG_BUS_EVENT = 0x00000010, + MCD_TRIG_ACTION_TRIG_BUS_SET = 0x00000020, + MCD_TRIG_ACTION_TRIG_BUS_CLEAR = 0x00000040, + MCD_TRIG_ACTION_TRACE_QUALIFY = 0x00000100, + MCD_TRIG_ACTION_TRACE_QUALIFY_PROGRAM = 0x00000200, + MCD_TRIG_ACTION_TRACE_QUALIFY_DATA = 0x00000400, + MCD_TRIG_ACTION_TRACE_START = 0x00000800, + MCD_TRIG_ACTION_TRACE_STOP = 0x00001000, + MCD_TRIG_ACTION_TRACE_TRIGGER = 0x00002000, + MCD_TRIG_ACTION_ANA_START_PERFM = 0x00010000, + MCD_TRIG_ACTION_ANA_STOP_PERFM = 0x00020000, + MCD_TRIG_ACTION_STATE_CHANGE = 0x00040000, + MCD_TRIG_ACTION_COUNT_QUALIFY = 0x00080000, + MCD_TRIG_ACTION_COUNT_START = 0x00100000, + MCD_TRIG_ACTION_COUNT_STOP = 0x00200000, + MCD_TRIG_ACTION_COUNT_RESTART = 0x00400000, + MCD_TRIG_ACTION_CUSTOM_LO = 0x01000000, + MCD_TRIG_ACTION_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_tx_access_type_et - Enumeration type defining access types for + * transactions of transaction lists. + * + * This enumeration type describes the four possible access types for + * transaction of a transaction list. + * + * * %MCD_TX_AT_R - Read access transaction. + * * %MCD_TX_AT_W - Write access transaction. + * * %MCD_TX_AT_RW - Read then write access transaction (atomic swap). + * * %MCD_TX_AT_WR - Write then read access transaction (write and verify). + */ +typedef uint32_t mcd_tx_access_type_et; +enum { + MCD_TX_AT_R = 0x00000001, + MCD_TX_AT_W = 0x00000002, + MCD_TX_AT_RW = 0x00000003, + MCD_TX_AT_WR = 0x00000004, +}; + + +/** + * typedef mcd_tx_access_opt_et - Enumeration type defining access options for + * transactions of transaction lists. + * + * This enumeration type describes the possible access options for transactions + * of a transaction list. The type values are bitwise mutually exclusive and a + * member of type mcd_tx_access_opt_et may be a combination of several of them. + * User defined access options need to have values between %MCD_TX_OPT_CUSTOM_LO + * and %MCD_TX_OPT_CUSTOM_HI. Reserved access options must not be used. + * + * Marking the last transaction of a transaction list with + * %MCD_TX_OPT_ATOMIC_WITH_NEXT causes it to be atomic with the first + * transaction of the next list to be executed for this core connection. + * + * * %MCD_TX_OPT_DEFAULT - MCD implementation decides on applied access options. + * * %MCD_TX_OPT_SIDE_EFFECTS - Trigger side effects for the access. + * * %MCD_TX_OPT_NO_SIDE_EFFECTS - Omit side effects for the access. + * * %MCD_TX_OPT_BURST_ACCESSES - Perform burst accesses if possible. + * * %MCD_TX_OPT_NO_BURST_ACCESSES - Avoid burst accesses if possible. + * * %MCD_TX_OPT_ALTERNATE_PATH - Dual port or DAP memory access. + * * %MCD_TX_OPT_PRIORITY_ACCESS - High priority access. + * * %MCD_TX_OPT_DCACHE_WRITE_THRU - Force D-cache and unified caches to be + * write-through. + * * %MCD_TX_OPT_CACHE_BYPASS - Bypass caches and read/write directly to the + * memory. + * * %MCD_TX_OPT_NOINCREMENT - Do not increment address after each cycle. Useful + * for reading or writing to FIFOs. + * * %MCD_TX_OPT_ATOMIC_WITH_NEXT - Transaction is executed atomic with the next + * one. + * * %MCD_TX_OPT_RESERVED_LO - Begin Range: Reserved for future API use. + * * %MCD_TX_OPT_RESERVED_HI - End Range: Reserved for future API use. + * * %MCD_TX_OPT_CUSTOM_LO - Begin Range: User defined access options. + * * %MCD_TX_OPT_CUSTOM_HI - End Range: User defined access options. + */ +typedef uint32_t mcd_tx_access_opt_et; +enum { + MCD_TX_OPT_DEFAULT = 0x00000000, + MCD_TX_OPT_SIDE_EFFECTS = 0x00000001, + MCD_TX_OPT_NO_SIDE_EFFECTS = 0x00000002, + MCD_TX_OPT_BURST_ACCESSES = 0x00000004, + MCD_TX_OPT_NO_BURST_ACCESSES = 0x00000008, + MCD_TX_OPT_ALTERNATE_PATH = 0x00000010, + MCD_TX_OPT_PRIORITY_ACCESS = 0x00000020, + MCD_TX_OPT_DCACHE_WRITE_THRU = 0x00000040, + MCD_TX_OPT_CACHE_BYPASS = 0x00000080, + MCD_TX_OPT_NOINCREMENT = 0x00000100, + MCD_TX_OPT_ATOMIC_WITH_NEXT = 0x00000200, + MCD_TX_OPT_RESERVED_LO = 0x00000400, + MCD_TX_OPT_RESERVED_HI = 0x00008000, + MCD_TX_OPT_CUSTOM_LO = 0x00010000, + MCD_TX_OPT_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_core_step_type_et - Enumeration type defining step types for a + * target core. + * + * This enumeration type describes the possible step types for a target core. + * The step type depends on the core type. A programmable core can be for + * example stepped in terms of cycles or instructions. User defined step types + * need to have values between %MCD_CORE_STEP_TYPE_CUSTOM_LO and + * %MCD_CORE_STEP_TYPE_CUSTOM_HI. They for example can be based on + * specifications provided by the IP developer of a core. The step type values + * %MCD_CORE_STEP_TYPE_RESERVED_LO to %MCD_CORE_STEP_TYPE_RESERVED_HI are + * reserved for future API extensions and must not be used. + * + * * %MCD_CORE_STEP_TYPE_CYCLES - Step the core for core specific cycles. + * * %MCD_CORE_STEP_TYPE_INSTR - Step the core for core specific instructions. + * * %MCD_CORE_STEP_TYPE_RESERVED_LO - Begin Range: Reserved for future API use. + * * %MCD_CORE_STEP_TYPE_RESERVED_HI - End Range: Reserved for future API use. + * * %MCD_CORE_STEP_TYPE_CUSTOM_LO - Begin Range: User defined step types. + * * %MCD_CORE_STEP_TYPE_CUSTOM_HI - End Range: User defined step types. + * * %MCD_CORE_STEP_TYPE_MAX_TYPES - Maximum number of supported step types. + */ +typedef uint32_t mcd_core_step_type_et; +enum { + MCD_CORE_STEP_TYPE_CYCLES = 0x00000001, + MCD_CORE_STEP_TYPE_INSTR = 0x00000002, + MCD_CORE_STEP_TYPE_RESERVED_LO = 0x00000004, + MCD_CORE_STEP_TYPE_RESERVED_HI = 0x000000FF, + MCD_CORE_STEP_TYPE_CUSTOM_LO = 0x00000100, + MCD_CORE_STEP_TYPE_CUSTOM_HI = 0x00000F00, + MCD_CORE_STEP_TYPE_MAX_TYPES = 0x7FFFFFFF +}; + + +/** + * typedef mcd_core_state_et - Enumeration type defining the execution states of + * a target core. + * + * This enumeration type describes the possible execution states of a target + * core from a debugger perspective. The HALTED state is defined to differ from + * the DEBUG state by the fact that a core in debug mode is under debugger + * control. In contrast to this a core in HALTED state is not under the + * execution control of the debugger but in a state from which the debugger can + * only push it to DEBUG state. The same applies to the RUNNING state. User + * defined core states need to have values between %MCD_CORE_STATE_CUSTOM_LO and + * %MCD_CORE_STATE_CUSTOM_HI. + * + * * %MCD_CORE_STATE_UNKNOWN - Target core state is unknown. + * * %MCD_CORE_STATE_RUNNING - Target core is running. + * * %MCD_CORE_STATE_HALTED - Target core is halted. + * * %MCD_CORE_STATE_DEBUG - Target core is in debug mode. + * * %MCD_CORE_STATE_CUSTOM_LO - Begin Range: User defined core states. + * * %MCD_CORE_STATE_CUSTOM_HI - End Range: User defined core states. + * * %MCD_CORE_STATE_MAX_STATES - Maximum number of supported core states. + */ +typedef uint32_t mcd_core_state_et; +enum { + MCD_CORE_STATE_UNKNOWN = 0x00000000, + MCD_CORE_STATE_RUNNING = 0x00000001, + MCD_CORE_STATE_HALTED = 0x00000002, + MCD_CORE_STATE_DEBUG = 0x00000003, + MCD_CORE_STATE_CUSTOM_LO = 0x00000100, + MCD_CORE_STATE_CUSTOM_HI = 0x00000800, + MCD_CORE_STATE_MAX_STATES = 0x7FFFFFFF +}; + + +/** + * typedef mcd_core_event_et - Enumeration type defining the possible events for + * a target core. + * + * This enumeration type describes the possible core events for a target core + * from a debugger perspective. These allow to optimize the polling of specific + * target information and to support multiple clients connected to one target + * core. Some core events may be reported just once. User defined core events + * need to have values between %MCD_CORE_EVENT_CUSTOM_LO and + * %MCD_CORE_EVENT_CUSTOM_HI. + * + * * %MCD_CORE_EVENT_NONE - No since the last poll. + * * %MCD_CORE_EVENT_MEMORY_CHANGE - Memory content has changed. + * * %MCD_CORE_EVENT_REGISTER_CHANGE - Register contents have changed. + * * %MCD_CORE_EVENT_TRACE_CHANGE - Trace contents or states have changed. + * * %MCD_CORE_EVENT_TRIGGER_CHANGE - Triggers or trigger states have changed. + * * %MCD_CORE_EVENT_STOPPED - Target was stopped at least once since the last + * poll, it may already be running again. + * * %MCD_CORE_EVENT_CHL_PENDING - A target communication channel request from + * the target is pending. + * * %MCD_CORE_EVENT_CUSTOM_LO - Begin Range: User defined core events. + * * %MCD_CORE_EVENT_CUSTOM_HI - End Range: User defined core events. + */ +typedef uint32_t mcd_core_event_et; +enum { + MCD_CORE_EVENT_NONE = 0x00000000, + MCD_CORE_EVENT_MEMORY_CHANGE = 0x00000001, + MCD_CORE_EVENT_REGISTER_CHANGE = 0x00000002, + MCD_CORE_EVENT_TRACE_CHANGE = 0x00000004, + MCD_CORE_EVENT_TRIGGER_CHANGE = 0x00000008, + MCD_CORE_EVENT_STOPPED = 0x00000010, + MCD_CORE_EVENT_CHL_PENDING = 0x00000020, + MCD_CORE_EVENT_CUSTOM_LO = 0x00010000, + MCD_CORE_EVENT_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_chl_type_et - Enumeration type defining the communication channel + * types. + * + * There can be different types of communication channels between a host side + * tool and the target. This enumeration describes these possible types of + * communication channels. User defined communication channel types need to have + * values between %MCD_CHL_TYPE_CUSTOM_LO and %MCD_CHL_TYPE_CUSTOM_HI. + * + * * %MCD_CHL_TYPE_COMMON - Common communication channel to the target. + * * %MCD_CHL_TYPE_CONFIG - Communication channel for configuration purposes, + * e.g. to configure the analysis setup. + * * %MCD_CHL_TYPE_APPLI - Communication channel to an application running on + * the target, e.g. for semi-hosting purposes. + * * %MCD_CHL_TYPE_CUSTOM_LO - Begin Range: User defined communication channel + * types. + * * %MCD_CHL_TYPE_CUSTOM_HI - End Range: User defined communication channel + * types. + */ +typedef uint32_t mcd_chl_type_et; +enum { + MCD_CHL_TYPE_COMMON = 0x00000001, + MCD_CHL_TYPE_CONFIG = 0x00000002, + MCD_CHL_TYPE_APPLI = 0x00000003, + MCD_CHL_TYPE_CUSTOM_LO = 0x00000100, + MCD_CHL_TYPE_CUSTOM_HI = 0x00000F00, +}; + + +/** + * typedef mcd_chl_attributes_et - Enumeration type defining communication + * channel attributes. + * + * A communication channel can be defined with several attributes concerning the + * channel's direction, accessibility and priority. This enumeration type + * describes them. The type values are bitwise mutually exclusive and a member + * of type mcd_chl_attributes_et may be a combination of several of them. + * + * * %MCD_CHL_AT_RCV - Receive channel. + * * %MCD_CHL_AT_SND - Send channel. + * * %MCD_CHL_AT_MEM_MAPPED - Channel is memory mapped. + * * %MCD_CHL_AT_HAS_PRIO - Channel has a defined priority. + */ +typedef uint32_t mcd_chl_attributes_et; +enum { + MCD_CHL_AT_RCV = 0x00000001, + MCD_CHL_AT_SND = 0x00000002, + MCD_CHL_AT_MEM_MAPPED = 0x00000040, + MCD_CHL_AT_HAS_PRIO = 0x00000800, +}; + + +/** + * typedef mcd_trace_type_et - Enumeration type defining basic trace types. + * + * This enumeration type describes the type of a trace source. The type values + * are bitwise mutually exclusive. User defined trace types need to have values + * between %MCD_TRACE_TYPE_CUSTOM_LO and %MCD_TRACE_TYPE_CUSTOM_HI. + * + * * %MCD_TRACE_TYPE_UNKNOWN - Unknown trace source. + * * %MCD_TRACE_TYPE_CORE - Traces the instruction and (optional) data trace + * stream as seen from the core. + * * %MCD_TRACE_TYPE_BUS - Traces a bus that is not related to the program flow. + * * %MCD_TRACE_TYPE_EVENT - Traces logical signals (can include buses) that + * have an asynchronous nature. + * * %MCD_TRACE_TYPE_STAT - Traces statistical or profiling information. + * * %MCD_TRACE_TYPE_CUSTOM_LO - Begin Range: User defined trace types. + * * %MCD_TRACE_TYPE_CUSTOM_HI - End Range: User defined trace types. + */ +typedef uint32_t mcd_trace_type_et; +enum { + MCD_TRACE_TYPE_UNKNOWN = 0x00000000, + MCD_TRACE_TYPE_CORE = 0x00000001, + MCD_TRACE_TYPE_BUS = 0x00000002, + MCD_TRACE_TYPE_EVENT = 0x00000004, + MCD_TRACE_TYPE_STAT = 0x00000008, + MCD_TRACE_TYPE_CUSTOM_LO = 0x00000100, + MCD_TRACE_TYPE_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_trace_format_et - Enumeration type defining trace data formats. + * + * This enumeration type describes the format of the trace data. Each trace + * source can deliver data in exactly one format, only. Standard formats should + * be used whenever possible. User defined trace types need to have values + * between %MCD_TRACE_FORMAT_CUSTOM_LO and %MCD_TRACE_FORMAT_CUSTOM_HI. + * + * * %MCD_TRACE_FORMAT_UNKNOWN - Trace data format not readable via API. + * * %MCD_TRACE_FORMAT_CORE_FETCH - Execution trace extracted from bus fetch + * cycles (use struct mcd_trace_data_core_st for this format). + * * %MCD_TRACE_FORMAT_CORE_EXECUTE - Execution trace (use struct + * mcd_trace_data_core_st for this format) + * * %MCD_TRACE_FORMAT_CORE_FLOW_ICOUNT - Flowtrace data format similar to NEXUS + * traces, instruction count (use struct mcd_trace_data_core_st for this + * format). + * * %MCD_TRACE_FORMAT_CORE_FLOW_BCOUNT - Flowtrace data format similar to NEXUS + * traces, bytes count (use struct mcd_trace_data_core_st for this format). + * * %MCD_TRACE_FORMAT_CORE_FLOW_IPREDICATE - Flowtrace data format with + * predicates and instruction count (use struct mcd_trace_data_core_st for + * this format). + * * %MCD_TRACE_FORMAT_EVENT - Logic and system event trace (use struct + * mcd_trace_data_event_st for this format). + * * %MCD_TRACE_FORMAT_STAT - Statistics trace (use struct + * mcd_trace_data_stat_st for this format). + * * %MCD_TRACE_FORMAT_CUSTOM_LO - Begin Range: User defined trace data formats. + * * %MCD_TRACE_FORMAT_CUSTOM_HI - End Range: User defined trace data formats. + */ +typedef uint32_t mcd_trace_format_et; +enum { + MCD_TRACE_FORMAT_UNKNOWN = 0x00000000, + MCD_TRACE_FORMAT_CORE_FETCH = 0x00000001, + MCD_TRACE_FORMAT_CORE_EXECUTE = 0x00000002, + MCD_TRACE_FORMAT_CORE_FLOW_ICOUNT = 0x00000003, + MCD_TRACE_FORMAT_CORE_FLOW_BCOUNT = 0x00000004, + MCD_TRACE_FORMAT_CORE_FLOW_IPREDICATE = 0x00000005, + MCD_TRACE_FORMAT_EVENT = 0x00000010, + MCD_TRACE_FORMAT_STAT = 0x00000020, + MCD_TRACE_FORMAT_CUSTOM_LO = 0x00000100, + MCD_TRACE_FORMAT_CUSTOM_HI = 0x7FFFFFFF, +}; + + +/** + * typedef mcd_trace_mode_et - Enumeration type defining operation modes of a + * trace buffer. + * + * This enumeration type describes the possible operation modes of a trace + * buffer. The type values are bitwise mutually exclusive. User defined + * operation modes need to have values between %MCD_TRACE_MODE_CUSTOM_LO and + * %MCD_TRACE_MODE_CUSTOM_HI. + * + * * %MCD_TRACE_MODE_NOCHANGE - Do not change trace buffer mode. + * * %MCD_TRACE_MODE_FIFO - Circular trace buffer. + * * %MCD_TRACE_MODE_STACK - Trace stops when buffer is full. + * * %MCD_TRACE_MODE_LEACH - Target is stopped (brought into debug state) when + * buffer is almost full. + * * %MCD_TRACE_MODE_PIPE - Trace data are continuously streamed through API, + * buffer is a FIFO for temporary storage. + * * %MCD_TRACE_MODE_CUSTOM_LO - Begin Range: User defined operation modes. + * * %MCD_TRACE_MODE_CUSTOM_HI - End Range: User defined operation modes. + */ +typedef uint32_t mcd_trace_mode_et; +enum { + MCD_TRACE_MODE_NOCHANGE = 0x00000000, + MCD_TRACE_MODE_FIFO = 0x00000001, + MCD_TRACE_MODE_STACK = 0x00000002, + MCD_TRACE_MODE_LEACH = 0x00000004, + MCD_TRACE_MODE_PIPE = 0x00000008, + MCD_TRACE_MODE_CUSTOM_LO = 0x00000100, + MCD_TRACE_MODE_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_trace_state_et - Enumeration type defining trace states. + * + * This enumeration type describes the possible states of a trace. User defined + * trace states need to have values between %MCD_TRACE_STATE_CUSTOM_LO and + * %MCD_TRACE_STATE_CUSTOM_HI. + * + * * %MCD_TRACE_STATE_NOCHANGE - Do not change state (only for + * mcd_set_trace_state_f()). + * * %MCD_TRACE_STATE_DISABLE - Trace is disabled and no resources are + * allocated. + * * %MCD_TRACE_STATE_OFF - Trace is off and does not trace data, but is ready + * for tracing. + * * %MCD_TRACE_STATE_ARM - Trace is armed. + * * %MCD_TRACE_STATE_TRIGGER - Trace is triggered and waits for the post + * trigger delay. + * * %MCD_TRACE_STATE_STOP - Trace has stopped (after trigger and post trigger + * delay have elapsed). + * * %MCD_TRACE_STATE_INIT - Clears trace buffer and goes into OFF state (only + * for mcd_set_trace_state_f()). + * * %MCD_TRACE_STATE_CUSTOM_LO - Begin Range: User defined trace states. + * * %MCD_TRACE_STATE_CUSTOM_HI - End Range: User defined trace states. + */ +typedef uint32_t mcd_trace_state_et; +enum { + + MCD_TRACE_STATE_NOCHANGE = 0x00000000, + MCD_TRACE_STATE_DISABLE = 0x00000001, + MCD_TRACE_STATE_OFF = 0x00000002, + MCD_TRACE_STATE_ARM = 0x00000003, + MCD_TRACE_STATE_TRIGGER = 0x00000004, + MCD_TRACE_STATE_STOP = 0x00000005, + MCD_TRACE_STATE_INIT = 0x00000010, + MCD_TRACE_STATE_CUSTOM_LO = 0x00000100, + MCD_TRACE_STATE_CUSTOM_HI = 0x7FFFFFFF, +}; + + +/** + * typedef mcd_trace_marker_et - Enumeration type defining trace markers. + * + * This enumeration type describes markers associated with a single trace frame. + * The type values are bitwise mutually exclusive and a member of type + * mcd_trace_marker_et may be a combination of several of them. User defined + * trace markers need to have values between %MCD_TRACE_MARKER_CUSTOM_LO and + * %MCD_TRACE_MARKER_CUSTOM_HI. + * + * * %MCD_TRACE_MARKER_NONE - No marker set. + * * %MCD_TRACE_MARKER_RUN - Core has started execution in this trace frame + * (first cycle). + * * %MCD_TRACE_MARKER_DEBUG - Core has stopped execution in this trace frame + * (last cycle). + * * %MCD_TRACE_MARKER_START - Tracing has started in this trace frame + * (controlled by trigger). + * * %MCD_TRACE_MARKER_STOP - Tracing has stopped in this trace frame + * (controlled by trigger). + * * %MCD_TRACE_MARKER_ERROR - Error marker (hardware failure or program flow + * reconstruction error). + * * %MCD_TRACE_MARKER_GAP - Gap in trace (caused by bandwidth limitation on + * trace port). + * * %MCD_TRACE_MARKER_CUSTOM_LO - Begin Range: User defined trace markers. + * * %MCD_TRACE_MARKER_CUSTOM_HI - End Range: User defined trace markers. + */ +typedef uint32_t mcd_trace_marker_et; +enum { + MCD_TRACE_MARKER_NONE = 0x00000000, + MCD_TRACE_MARKER_RUN = 0x00000001, + MCD_TRACE_MARKER_DEBUG = 0x00000002, + MCD_TRACE_MARKER_START = 0x00000004, + MCD_TRACE_MARKER_STOP = 0x00000008, + MCD_TRACE_MARKER_ERROR = 0x00000010, + MCD_TRACE_MARKER_GAP = 0x00000020, + MCD_TRACE_MARKER_CUSTOM_LO = 0x00000100, + MCD_TRACE_MARKER_CUSTOM_HI = 0x40000000, +}; + + +/** + * typedef mcd_trace_cycle_et - Enumeration type defining basic trace cycles. + * + * This enumeration type describes the basic trace cycle types for bus and core + * traces. User defined trace cycle types need to have values between + * %MCD_TRACE_CYCLE_CUSTOM_LO and %MCD_TRACE_CYCLE_CUSTOM_HI. + * + * * %MCD_TRACE_CYCLE_UNKNOWN - Trace cycle contains no valid data for this + * core. + * * %MCD_TRACE_CYCLE_NONE - No trace cycle, control information (marker, + * timestamp) is valid. + * * %MCD_TRACE_CYCLE_EXECUTE - Program execution cycle, marks the execution of + * one instruction. For a program flow trace this marks the execution of a + * block which is ended with a taken branch. + * * %MCD_TRACE_CYCLE_NOTEXECUTE - Program execution cycle, marks the execution + * of one conditional instruction with a "failing" condition code. For a + * program flow trace this marks the execution of a block which is ended + * without a branch. + * * %MCD_TRACE_CYCLE_FETCH - Program fetch cycle, the instruction related to + * the cycle may just be prefetched. + * * %MCD_TRACE_CYCLE_READ - Data read cycle. + * * %MCD_TRACE_CYCLE_WRITE - Data write cycle. + * * %MCD_TRACE_CYCLE_OWNERSHIP - Ownership change cycle, usually indicates a + * change of the executed software thread. + * * %MCD_TRACE_CYCLE_CUSTOM_LO - Begin Range: User defined trace cycles. + * * %MCD_TRACE_CYCLE_CUSTOM_HI - End Range: User defined trace cycles. + */ +typedef uint32_t mcd_trace_cycle_et; +enum { + MCD_TRACE_CYCLE_UNKNOWN = 0x00000000, + MCD_TRACE_CYCLE_NONE = 0x00000001, + MCD_TRACE_CYCLE_EXECUTE = 0x00000002, + MCD_TRACE_CYCLE_NOTEXECUTE = 0x00000003, + MCD_TRACE_CYCLE_FETCH = 0x00000004, + MCD_TRACE_CYCLE_READ = 0x00000005, + MCD_TRACE_CYCLE_WRITE = 0x00000006, + MCD_TRACE_CYCLE_OWNERSHIP = 0x00000007, + MCD_TRACE_CYCLE_CUSTOM_LO = 0x00000100, + MCD_TRACE_CYCLE_CUSTOM_HI = 0x7FFFFFFF, +}; + + +/** + * DOC: Definition of Structures + * + * This is the list of data structures exchanged by the functions of the MCD + * API. + */ + + +/** + * struct mcd_api_version_st - Structure type containing the MCD API version + * information of the tool. + * + * @v_api_major: API major version. + * @v_api_minor: API minor version. + * @author: API name of the author of this MCD API version. + * + * This structure type contains version information about the MCD API + * implementation of the tool. Reference version at end of SPRINT project is: + * + * * @v_api_major = 1 + * * @v_api_minor = 0 + * * @author = "SPRINT Release" + */ +typedef struct mcd_api_version_st { + uint16_t v_api_major; + uint16_t v_api_minor; + char author[MCD_API_IMP_VENDOR_LEN]; +} mcd_api_version_st; + + +/** + * struct mcd_impl_version_info_st - Structure type containing the MCD API + * implementation information. + * + * @v_api: Implemented API version. + * @v_imp_major: Major version number of this implementation. + * @v_imp_minor: Minor version number of this implementation. + * @v_imp_build: Build number of this implementation. + * @vendor: Name of vendor of the implementation. + * @date: String from __DATE__ macro at compile time. + * + * This structure type contains important information about the particular + * implementation of the MCD API. + */ +typedef struct mcd_impl_version_info_st { + mcd_api_version_st v_api; + uint16_t v_imp_major; + uint16_t v_imp_minor; + uint16_t v_imp_build; + char vendor[MCD_API_IMP_VENDOR_LEN]; + char date[16]; +} mcd_impl_version_info_st; + + +/** + * struct mcd_error_info_st - Structure type containing the error status and + * error event notification. + * + * @return_status: Return status from the last API call. + * @error_code: Detailed error code from the last API call. + * @error_events: Detailed event code from the last API call. + * @error_str: Detailed error text string from the last API call. + * + * All API functions return a value of type mcd_return_et. If this value + * indicates an error or an error event that has happened during the last API + * call, the calling function has to handle it appropriately. This can be + * achieved by asking for more information about the occurred error or error + * event. This structure type contains all the required details about the error + * and/or the error event as reported by the target. + */ +typedef struct mcd_error_info_st { + mcd_return_et return_status; + mcd_error_code_et error_code; + mcd_error_event_et error_events; + char error_str[MCD_INFO_STR_LEN]; +} mcd_error_info_st; + + +/** + * struct mcd_server_info_st - Structure type containing the server information. + * + * @server: String containing the server name. + * @system_instance: String containing the unique system instance identifier. + * @acc_hw: String containing the unique device access hardware name. + * + * This structure type contains the information about a running or an installed + * server. + * + * @server contains a string with the server name. For a running simulation + * server, @system_instance has the same value as @system_instance in + * mcd_core_con_info_st, and @acc_hw contains an empty string. For a real + * hardware server it is the other way around. + */ +typedef struct mcd_server_info_st { + char server[MCD_UNIQUE_NAME_LEN]; + char system_instance[MCD_UNIQUE_NAME_LEN]; + char acc_hw[MCD_UNIQUE_NAME_LEN]; +} mcd_server_info_st; + + +/** + * struct mcd_server_st - Structure type containing the server connection + * instance. + * + * @instance: Server connection instance of an implementation at lower level. + * @host: String containing the host name. + * @config_string: Server configuration information. + * + * This structure type contains a server connection instance. + * + * For the MCD API a server provides the capability to connect to a system, its + * devices and/or cores. A server can arrange connections to several systems. A + * system again consists of devices and cores, where devices may subsume + * several cores, e.g. a SoC on a real hardware board. Consequently, a + * multi-core simulation is a system with several processor cores. + */ +typedef struct mcd_server_st { + void *instance; + const char *host; + const char *config_string; +} mcd_server_st; + + +/** + * struct mcd_core_con_info_st - Structure type containing the core connection + * information. + * + * @host: String containing the IP host name. + * @server_port: Port number of the server. + * @server_key: String containing the server key as provided by + * mcd_open_server_f(). + * @system_key: String containing the system key as provided by + * mcd_open_server_f(). + * @device_key: String containing the device key, optional for + * mcd_open_core_f(). + * @system: String containing the system name. Predefined value is + * "Real HW" for physical devices. Note that in case of "Real + * HW" the @acc_hw always needs to be defined. + * @system_instance: String containing the unique system instance identifier. + * Allows to differentiate between several system instances + * with the same name. A typical use case is a simulator where + * different instances can be distinguished by their process + * ID. (For example @system_instance could be: "Process ID: + * 1234") + * @acc_hw: String containing the unique device access hardware name. + * @device_type: Device type identifier (IEEE 1149.1 device ID) + * @device: String containing the system unique device instance name. + * For Real HW this is usually the sales name of the device. + * If the access hardware operates a multi device target + * system (e.g. over IEEE1149.7), this device string can + * contain an index to differentiate between several devices + * of the same type. + * @device_id: Unique device ID. + * @core: String containing the device unique core name. + * @core_type: Core type identifier (taken from ELF predefined + * architecture) + * @core_id: Unique core ID representing the core version. + * + * The MCD hierarchy's top-level is a system. The next level are devices and + * followed by cores at the lowest level are cores. The MCD API is core centric, + * i.e. connections are established to specific cores and not to a device or a + * system. The core connection information is used to open this connection with + * mcd_open_core_f(). In order to establish a core connection, the core + * connection information does not have to complete but it has to be + * unambiguous. A set of hierarchical query functions, starting at system level, + * allows to parse each system top down. It is recommended to exclude + * unnecessary and redundant hierarchy information from @core and @device. + * @device needs to be readable and unambiguous within a @system. @core again + * has to be readable and unambiguous within its superior @device instance. + * + * This structure type contains all information required to establish a core + * connection. + */ +typedef struct mcd_core_con_info_st { + char host[MCD_HOSTNAME_LEN]; + uint32_t server_port; + char server_key[MCD_KEY_LEN]; + char system_key[MCD_KEY_LEN]; + char device_key[MCD_KEY_LEN]; + char system[MCD_UNIQUE_NAME_LEN]; + char system_instance[MCD_UNIQUE_NAME_LEN]; + char acc_hw[MCD_UNIQUE_NAME_LEN]; + uint32_t device_type; + char device[MCD_UNIQUE_NAME_LEN]; + uint32_t device_id; + char core[MCD_UNIQUE_NAME_LEN]; + uint32_t core_type; + uint32_t core_id; +} mcd_core_con_info_st; + + +/** + * struct mcd_core_st - Structure type containing the core connection instance. + * + * @instance: Core connection instance of an implementation at lower level. + * This void pointer must not be null except from function calls + * concerning communication channels. For these calls, null + * pointers are allowed in order to address hierarchical levels + * higher than core level. + * @core_con_info: Core connection information of the core instance. + * + * This structure type contains a core connection instance. + */ +typedef struct mcd_core_st { + void *instance; + const mcd_core_con_info_st *core_con_info; +} mcd_core_st; + + +/** + * struct mcd_core_mode_info_st - Structure type containing information about a + * core mode. + * + * @core_mode: Contains one of the 32 possible core modes, + * values can be 1 to 32. + * @name: The name of this core mode. + * + * This structure type contains information about a specific core mode. Most + * cores have for example "supervisor" or "user" operation modes. @core_mode can + * be a value within the range of 1 to 32. Some API structures contain bitmasks + * of which each bit corresponds to @core_mode of exactly one core mode (bit 0 + * corresponds to core mode 1). Core mode 0 is used to define a default core + * mode - usually the most permissive core mode. + */ +typedef struct mcd_core_mode_info_st { + uint8_t core_mode; + char name[MCD_CORE_MODE_NAME_LEN]; +} mcd_core_mode_info_st; + + +/** + * struct mcd_addr_st - Structure type containing a completely resolved logical + * or physical memory address. + * + * @address: Address value within a memory space, expressed in bytes. + * @mem_space_id: ID of the memory space associated with this address, e.g. a + * program memory, a data memory or registers . + * @addr_space_id: ID of the address space in which this address is valid. + * @addr_space_type: Type of the address space in which this address is valid. + * + * This structure type contains a completely resolved logical or physical memory + * address. The @address is always expressed in bytes, even if the minimum + * access unit (MAU) size is larger than a byte. The + * @addr_space_id can be used for different purposes as defined by + * @addr_space_type. + */ +typedef struct mcd_addr_st { + uint64_t address; + uint32_t mem_space_id; + uint32_t addr_space_id; + mcd_addr_space_type_et addr_space_type; +} mcd_addr_st; + + +/** + * struct mcd_memspace_st - Structure type containing information about a memory + * space. + * + * @mem_space_id: ID of this memory space, ID 0 is reserved. + * @mem_space_name: Unique name of the memory space. + * @mem_type: Type of the memory space. + * @bits_per_mau: Bits per minimum addressable unit (MAU). The + * minimum addressable unit of a memory is defined as + * the size in bits of its basic block that may have + * a unique address. For example for a byte + * addressable memory this value would be set to '8' + * according to the 8 bits of a byte block. + * @invariance: The total number of bytes in a memory word, which + * is @bits_per_mau divided by 8, consists of groups + * of "invariant" bytes. These groups can be arranged + * in Big Endian or Little Endian order. + * For example an @invariance of '2' and '64' + * @bits_per_mau, a Little Endian word are + * represented as b0 b1 b2 b3 b4 b5 b6 b7. + * In contrast to this, a Big Endian word is + * represented as b6 b7 b4 b5 b2 b3 b0 b1. + * @endian: Endianness of this memory space. Can be overriden + * by @endian of a mcd_memblock_st. + * @min_addr: Minimum address of this memory space. + * @max_addr: Maximum address of this memory space. + * @num_mem_blocks: Number of memory blocks in this memory space. Each + * memory space may have a certain number of memory + * blocks. Memory blocks contain additional + * information pertaining to the intended purpose of + * the memory. This information may be used as a hint + * for memory data representation within a tool's + * memory view. This field specifies the number of + * memory blocks present in this memory space. + * @supported_access_options: Supported memory access options (OR'ed bitmask). + * Can be overriden by @supported_access_options of a + * mcd_memblock_st. + * @core_mode_mask_read: Mask of core modes for which read accesses are + * impossible. A set bit indicates that read accesses + * are denied in this mode. Bit 0 represents core + * mode '1', bit 31 represents core mode '32'. Can be + * overriden by + * @core_mode_mask_read of a mcd_memblock_st. + * @core_mode_mask_write: Mask of core modes for which write accesses are + * impossible; a set bit indicates that write + * accesses are denied in this mode. Bit 0 represents + * core mode '1', bit 31 represents core mode '32'. + * Can be overriden by + * @core_mode_mask_write of a mcd_memblock_st. + * + * This structure type contains information about a memory space. of a target + * core. A memory space defines a region of memory used in different processor + * architectures, e.g. "program" and "data" memory of a Harvard architecture or + * "P"/"X"/"Y"/"Z" of a DSP architecture. + * + * Users must note that the sematics used in order to access a cache memory are + * the same as for accessing regular memory. On the target side, each cache + * memory implementation must be provided as a different memory space with a + * unique memory space ID. All accesses to such a memory space must be + * understood by the target as debug access to the cache. + */ +typedef struct mcd_memspace_st { + uint32_t mem_space_id; + char mem_space_name[MCD_MEM_SPACE_NAME_LEN]; + mcd_mem_type_et mem_type; + uint32_t bits_per_mau; + uint8_t invariance; + mcd_endian_et endian; + uint64_t min_addr; + uint64_t max_addr; + uint32_t num_mem_blocks; + mcd_tx_access_opt_et supported_access_options; + uint32_t core_mode_mask_read; + uint32_t core_mode_mask_write; +} mcd_memspace_st; + + +/** + * struct mcd_memblock_st - Structure type containing information about a memory + * block. + * + * @mem_block_id: ID of this memory block, ID 0 is reserved. + * @mem_block_name: Memory block name. + * @has_children: Indicating that this block has children. + * @parent_id: ID of this block's parent (%MCD_MEM_BLOCK_NOPARENT + * if no parent exists). Memory blocks by definition + * can be hierarchical. This field describes the ID + * of the parent memory block. In case this memory + * block is at root level (and therefore has no + * parent) the @parent_id field has to be set to + * %MCD_MEM_BLOCK_NOPARENT. + * @start_addr: Start address of this block. + * @end_addr: End address of this block. + * @endian: Endianness of this memory block. Overrides @endian + * of the corresponding mcd_memspace_st. + * @supported_au_sizes: This array has a maximum of %MCD_MEM_AUSIZE_NUM + * entries. Each entry different from '0' indicates + * the permissible size of an addressable memory unit + * in bits. All entries represent an allowed multiple + * of the @bits_per_mau field in the corresponding + * mcd_memspace_st data structure. For example, the + * supported addressable unit sizes for a memory + * block in a memory space with '32' bits_per_mau + * would be {32, 64, 96, 128}. This array field would + * then contain the values {1, 2, 3, 4}. + * @supported_access_options: Supported memory access options (OR'ed bitmask). + * Overrides @supported_access_options of the + * corresponding mcd_memspace_st. + * @core_mode_mask_read: Mask of core modes for which read accesses are + * impossible. A set bit indicates that read accesses + * are denied in this mode. Bit 0 represents core + * mode '1', bit 31 represents core mode '32'. + * Overrides @core_mode_mask_read of the + * corresponding mcd_memspace_st. + * @core_mode_mask_write: Mask of core modes for which write accesses are + * impossible. A set bit indicates that write + * accesses are denied in this mode. Bit 0 represents + * core mode '1', bit 31 represents core mode '32'. + * Overrides @core_mode_mask_write of the + * corresponding mcd_memspace_st. + * + * This structure type contains information about a memory block. A memory + * block is defined as a continuous range of memory addresses with same + * properties. A memory block is owned by a memory space. + */ +typedef struct mcd_memblock_st { + uint32_t mem_block_id; + char mem_block_name[MCD_MEM_BLOCK_NAME_LEN]; + bool has_children; + uint32_t parent_id; + uint64_t start_addr; + uint64_t end_addr; + mcd_endian_et endian; + uint32_t supported_au_sizes[MCD_MEM_AUSIZE_NUM]; + mcd_tx_access_opt_et supported_access_options; + uint32_t core_mode_mask_read; + uint32_t core_mode_mask_write; +} mcd_memblock_st; + + +/** + * struct mcd_register_group_st - Structure type containing register group + * information. + * + * @reg_group_id: Contains the ID of this register group. A register group ID + * must be unique within the scope of a target core. ID '0' is + * reserved. + * @reg_group_name: The name of a register group. A register group name cannot + * be longer than %MCD_REG_NAME_LEN characters (use + * representative names). + * @n_registers: Number of registers part of this group. + * + * This structure type contains the properties of a register group of a target + * core. + */ +typedef struct mcd_register_group_st { + uint32_t reg_group_id; + char reg_group_name[MCD_REG_NAME_LEN]; + uint32_t n_registers; +} mcd_register_group_st; + + +/** + * struct mcd_register_info_st - Structure type containing register information + * for a single register. + * + * @addr: Either the address of a memory mapped register or + * the register address in a dedicated "register memory + * space" + * @reg_group_id: ID of the group this register belongs to. + * @regname: The name of a register. A register name cannot be + * longer than %MCD_REG_NAME_LEN characters (use + * representative names). + * @regsize: Register size in bits. + * @core_mode_mask_read: Mask of core modes for which read accesses are + * impossible. A set bit indicates that read accesses + * are denied in this mode. Bit 0 represents core mode + * '1', bit 31 represents core mode 32. Overrides + * @core_mode_mask_read of the corresponding + * mcd_memspace_st. + * @core_mode_mask_write: Mask of core modes for which write accesses are + * impossible. A set bit indicates that write accesses + * are denied in this mode. Bit 0 represents core mode + * '1', bit 31 represents core mode '32'. Overrides + * @core_mode_mask_write of the corresponding + * mcd_memspace_st. + * @has_side_effects_read: Reading this register can trigger side effects. + * @has_side_effects_write: Writing this register can trigger side effects. + * @reg_type: Register type (simple, compound or partial) + * @hw_thread_id: Hardware thread ID this register belongs to. The ID + * must be set to '0' if the register is not assigned + * to a hardware thread. + * + * This structure contains the properties of a single register of a target + * core. + */ +typedef struct mcd_register_info_st { + mcd_addr_st addr; + uint32_t reg_group_id; + char regname[MCD_REG_NAME_LEN]; + uint32_t regsize; + uint32_t core_mode_mask_read; + uint32_t core_mode_mask_write; + bool has_side_effects_read; + bool has_side_effects_write; + mcd_reg_type_et reg_type; + uint32_t hw_thread_id; +} mcd_register_info_st; + + +/** + * struct mcd_trig_info_st - Structure type containing information about trigger + * capabilities. + * + * @type: Supported trigger types (OR'ed bitmask). + * @option: Supported trigger options (OR'ed bitmask). + * @action: Supported trigger actions (OR'ed bitmask). + * @trig_number: Number of usable triggers (or 0 if number not known). + * @state_number: Number of states of the trigger set's state machine (or 0 if + * not known). + * @counter_number: Number of usable counters (or 0 if not known) + * @sw_breakpoints: True if software breakpoints via code patch are available. + * + * This structure type contains information about the trigger capabilities of a + * target. + * + * Note: @trig_number, @state_number and @counter_number should NOT be used to + * determine if the appropriate trigger resource is available. It can just + * provide hints about the maximum number. The availability should be checked + * evaluating @action. + */ +typedef struct mcd_trig_info_st { + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t trig_number; + uint32_t state_number; + uint32_t counter_number; + bool sw_breakpoints; +} mcd_trig_info_st; + + +/** + * struct mcd_ctrig_info_st - Structure type containing information about a + * custom trigger. + * + * @ctrig_id: Custom trigger ID, ID 0 is reserved. + * @info_str: Description of the custom trigger. + * + * This structure type contains information about a custom trigger. These custom + * triggers can be used via the mcd_trig_custom_st structure type. + * + * Note: This is NOT related to custom trigger formats - they use a format not + * defined by the MCD API. + */ +typedef struct mcd_ctrig_info_st { + uint32_t ctrig_id; + char info_str[MCD_INFO_STR_LEN]; +} mcd_ctrig_info_st; + + +/** + * struct mcd_trig_complex_core_st - Structure type containing information about + * a complex core trigger condition. + * + * @struct_size: Size of this structure in bytes. + * @type: Trigger type, for this structure type it must be one of: + * + * - %MCD_TRIG_TYPE_IP + * - %MCD_TRIG_TYPE_READ + * - %MCD_TRIG_TYPE_WRITE + * - %MCD_TRIG_TYPE_RW + * - %MCD_TRIG_TYPE_NOCYCLE + * + * @option: Adds further qualifiers to the trigger or overrides the + * behaviour (multiple options possible) + * @action: Action to be taken on trigger. Only one per trigger allowed. + * @action_param: Parameter for action - depends on the selected action. + * @modified: Set to "TRUE" on return of mcd_create_trig_f() if trigger + * was modified by implementation, untouched otherwise. + * @state_mask: Set bits indicate that this trigger is inactive when + * reaching the corresponding state of the state machine. Bit 0 + * represents state '1' of the state machine. Only to be + * considered if %MCD_TRIG_OPT_STATE_IS_CONDITION is set in + * @option. + * @addr_start: Start address for the address range the trigger shall be + * activated for. + * @addr_range: Size of the address range for the trigger (in bytes). If it + * is set to '0', the trigger is activated by an access to a + * single address. If it is set to '1', the range of addresses + * is two (@addr_start + 1). The address range can be + * "inverted" if %MCD_TRIG_OPT_OUT_OF_RANGE is set in @option. + * @data_start: Data comparison value of the trigger. Only considered if + * %MCD_TRIG_OPT_DATA_IS_CONDITION is set in @option. Setting + * option %MCD_TRIG_OPT_NOT_DATA activates the trigger on a + * data mismatch. + * @data_range: Size of the data value range for the trigger. If it is set + * to '0', the trigger is activated on a match with a single + * value. If it is set to '1', the range of values is two + * (@data_range + 1). Option %MCD_TRIG_OPT_SIGNED_DATA may be + * set in @option if the data shall be interpreted as signed. + * This usually also requires the option + * %MCD_TRIG_OPT_DATASIZE_IS_CONDITION to be set in @option. + * @data_mask: Only value bits are considered for which the mask is set to + * '0' + * @data_size: Size of the access in bytes. If set to '0' the size shall + * not be considered. Shall be only considered if + * %MCD_TRIG_OPT_DATASIZE_IS_CONDITION is set in @option. + * @hw_thread_id: ID of the hardware thread this trigger is associated with. + * @sw_thread_id: ID of the software thread this trigger is associated with. + * @core_mode_mask: Mask of core modes for which the trigger shall not be + * activated. A set bit disables the trigger for the + * corresponding mode. Bit 0 represents core mode '1', bit 31 + * represents core mode '32'. + * + * This structure type contains information about a complex core based trigger + * of the target system. + */ +typedef struct mcd_trig_complex_core_st { + uint32_t struct_size; + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t action_param; + bool modified; + uint32_t state_mask; + mcd_addr_st addr_start; + uint64_t addr_range; + uint64_t data_start; + uint64_t data_range; + uint64_t data_mask; + uint32_t data_size; + uint32_t hw_thread_id; + uint64_t sw_thread_id; + uint32_t core_mode_mask; +} mcd_trig_complex_core_st; + + +/** + * struct mcd_trig_simple_core_st - Structure type containing information about + * a simple core trigger condition. + * @struct_size: Size of this structure in bytes. + * @type: Trigger type, for this structure type it must be one of: + * + * - %MCD_TRIG_TYPE_IP + * - %MCD_TRIG_TYPE_READ + * - %MCD_TRIG_TYPE_WRITE + * - %MCD_TRIG_TYPE_RW + * - %MCD_TRIG_TYPE_NOCYCLE + * + * @option: Adds further qualifiers to the trigger or overrides the + * behaviour (multiple options possible) + * @action: Action to be taken on trigger. Only one per trigger allowed. + * @action_param: Parameter for action - depends on the selected action. + * @modified: Set to "TRUE" on return of mcd_create_trig_f() if trigger + * was modified by implementation, untouched otherwise. + * @state_mask: Set bits indicate that this trigger is inactive when + * reaching the corresponding state of the state machine. Bit 0 + * represents state '1' of the state machine. Only to be + * considered if %MCD_TRIG_OPT_STATE_IS_CONDITION is set in + * @option. + * @addr_start: Start address for the address range the trigger shall be + * activated for. + * @addr_range: Size of the address range for the trigger (in bytes). If it + * is set to '0', the trigger is activated by an access to a + * single address. If it is set to '1', the range of addresses + * is two (@addr_start + 1). The address range can be + * "inverted" if %MCD_TRIG_OPT_OUT_OF_RANGE is set in @option. + * + * This structure type contains information about a simple core based trigger of + * the target system. It is a subset of mcd_trig_complex_core_st. + */ +typedef struct mcd_trig_simple_core_st { + uint32_t struct_size; + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t action_param; + bool modified; + uint32_t state_mask; + mcd_addr_st addr_start; + uint64_t addr_range; +} mcd_trig_simple_core_st; + + +/** + * struct mcd_trig_trig_bus_st - Structure type containing information about a + * trigger bus based trigger condition. + * + * @struct_size: Size of this structure in bytes. + * @type: Trigger type, for this structure type it must be + * %MCD_TRIG_TYPE_TRIG_BUS. + * @option: Trigger options, for this structure the following are + * allowed: + * + * - %MCD_TRIG_OPT_NOT + * - %MCD_TRIG_OPT_STATE_IS_CONDITION + * + * @action: Action to be taken on trigger. Only one per trigger allowed. + * @action_param: Parameter for action - depends on the selected action. + * @modified: Set to "TRUE" on return of mcd_create_trig_f() if trigger + * was modified by implementation, untouched otherwise. + * @state_mask: Set bits indicate that this trigger is inactive when + * reaching the corresponding state of the state machine. Bit 0 + * represents state '1' of the state machine. Only to be + * considered if %MCD_TRIG_OPT_STATE_IS_CONDITION is set in + * @option. + * @trig_bus_value: Trigger bus value. + * @trig_bus_mask: Only value bits are considered for which the bitmask is set + * to '0'. + * + * Trigger buses exist that can be optionally activated. This structure type + * contains information about a trigger on the target system based on such a + * trigger bus. + * + * A trigger bus is split into a core local trigger (bits 0 to 15) and a global + * trigger (bits 16 to 31). On real silicon some bits of the trigger bus may + * also be available on device pins. + */ +typedef struct mcd_trig_trig_bus_st { + uint32_t struct_size; + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t action_param; + bool modified; + uint32_t state_mask; + uint32_t trig_bus_value; + uint32_t trig_bus_mask; + +} mcd_trig_trig_bus_st; + + +/** + * struct mcd_trig_counter_st - Structure type containing information about a + * trigger counter on the target. + * + * @struct_size: Size of this s tructure in bytes. + * @type: Trigger type, for this structure type it must be + * %MCD_TRIG_TYPE_TRIG_COUNTER. + * @option: Trigger options, for this structure the following are + * allowed: + * + * - %MCD_TRIG_OPT_NOT + * - %MCD_TRIG_OPT_STATE_IS_CONDITION + * + * @action: Action to be taken on trigger. Only one per trigger allowed. + * @action_param: Parameter for action - depends on the selected action. + * @modified: Set to "TRUE" on return of mcd_create_trig_f() if trigger + * was modified by implementation, untouched otherwise. + * @state_mask: Set bits indicate that this trigger is inactive when + * reaching the corresponding state of the state machine. Bit 0 + * represents state '1' of the state machine. Only to be + * considered if %MCD_TRIG_OPT_STATE_IS_CONDITION is set in + * @option. + * @count_value: Current value of counter. + * @reload_value: Reload value of counter. + * + * This structure type contains information about a trigger counter on the + * target system. + */ +typedef struct mcd_trig_counter_st { + uint32_t struct_size; + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t action_param; + bool modified; + uint32_t state_mask; + uint64_t count_value; + uint64_t reload_value; +} mcd_trig_counter_st; + + +/** + * struct mcd_trig_custom_st - Structure type containing information about a + * custom trigger on the target. + * + * @struct_size: Size of this structure in bytes. + * @type: Trigger type, for this structure type it must be + * %MCD_TRIG_TYPE_CUSTOM. + * @option: Trigger options, for this structure the following are + * allowed: + * + * - %MCD_TRIG_OPT_NOT + * - %MCD_TRIG_OPT_STATE_IS_CONDITION + * + * @action: Action to be taken on trigger. Only one per trigger allowed. + * @action_param: Parameter for action - depends on the selected action. + * @modified: Set to "TRUE" on return of mcd_create_trig_f() if trigger + * was modified by implementation, untouched otherwise. + * @state_mask: Set bits indicate that this trigger is inactive when + * reaching the corresponding state of the state machine. Bit 0 + * represents state '1' of the state machine. Only to be + * considered if %MCD_TRIG_OPT_STATE_IS_CONDITION is set in + * @option. + * @ctrig_id: Custom trigger ID. + * @ctrig_args: Custom trigger arguments. + * + * This structure type contains information about a custom trigger on the target + * system. + */ +typedef struct mcd_trig_custom_st { + uint32_t struct_size; + mcd_trig_type_et type; + mcd_trig_opt_et option; + mcd_trig_action_et action; + uint32_t action_param; + bool modified; + uint32_t state_mask; + uint32_t ctrig_id; + uint32_t ctrig_args[4]; +} mcd_trig_custom_st; + + +/** + * struct mcd_trig_state_st - Structure type containing a trigger state. + * + * @active: Was active at the point of time the trigger set was + * uploaded. + * @captured: Activated at least once after trigger got downloaded to the + * target. + * @captured_valid: The information in @captured is valid. + * @count_value: Current value of the counter (for counter triggers). + * @count_valid: The information in @count_value is valid. + * + * This structure type contains the state of a single trigger on the target + * system. + */ +typedef struct mcd_trig_state_st { + bool active; + bool captured; + bool captured_valid; + uint64_t count_value; + bool count_valid; +} mcd_trig_state_st; + + +/** + * struct mcd_trig_set_state_st - Structure type containing a trigger set state. + * + * @active: Set if the trigger set is currently active. + * @state: Current state of the trigger set's state machine. + * @state_valid: Current state is valid. + * @trig_bus: Current state of trigger bus. + * @trig_bus_valid: Current state of trig_bus is valid. + * @trace: Current state of trace start/stop. + * @trace_valid: Current state is valid. + * @analysis: Current state of performance analysis start/stop. + * @analysis_valid: Current state is valid. + * + * This structure type contains the state of the trigger set of the target + * system. + */ +typedef struct mcd_trig_set_state_st { + bool active; + uint32_t state; + bool state_valid; + uint32_t trig_bus; + bool trig_bus_valid; + bool trace; + bool trace_valid; + bool analysis; + bool analysis_valid; +} mcd_trig_set_state_st; + + +/** + * struct mcd_tx_st - Structure type containing information about a single + * transaction. + * + * @addr: The address of the first memory cell/register. + * @access_type: Type of access: Read/Write/Read+Write/Write+Verify. + * @options: Access options: burst, side-effects, alternate path, cache, + * etc. + * @access_width: Access size in bytes (or 0 if access size does not matter). + * @core_mode: The core mode in which the access should be performed (or 0 + * for most permissive mode). + * @data: Byte array of size @num_bytes storing the access data. + * @num_bytes: Size of the memory/register access. The buffer @data needs to + * be of this size. + * @num_bytes_ok: Number of successfully received/sent bytes. + * + * This structure type contains all information required for a single + * transaction. The transaction itself can be a memory read/write operation or a + * register read/write operation. + * + * For memory access transactions, the data is stored to the buffer in the + * target's endianess format. For register access transaction, the data is + * stored to the buffer in Little Endian format. Targets need to read/fill the + * buffer, accordingly. + */ +typedef struct mcd_tx_st { + mcd_addr_st addr; + mcd_tx_access_type_et access_type; + mcd_tx_access_opt_et options; + uint8_t access_width; + uint8_t core_mode; + uint8_t *data; + uint32_t num_bytes; + uint32_t num_bytes_ok; +} mcd_tx_st; + + +/** + * struct mcd_txlist_st - Structure type containing a transaction list. + * + * @tx: Array of size @num_tx storing the transactions. + * @num_tx: Number of transactions. + * @num_tx_ok: Number of transactions which succeeded without any errors. + * + * This structure type contains a transaction list. + */ +typedef struct mcd_txlist_st { + mcd_tx_st *tx; + uint32_t num_tx; + uint32_t num_tx_ok; +} mcd_txlist_st; + + +/** + * struct mcd_core_state_st - Structure type containing the state of a core. + * + * @state: Core state. + * @event: Core events (OR'ed bitmask) + * @hw_thread_id: ID of the hardware thread that caused the core to stop. + * @trig_id: ID of the trigger that caused the core to stop. + * @stop_str: Detailed description of a special stop reason. + * @info_str: Detailed description of the core state. + * + * This structure type contains information about the state of a core. + * + * Note that the additional information provided in @info_str is not a + * repetition of the general core state provided by @state. + */ +typedef struct mcd_core_state_st { + mcd_core_state_et state; + mcd_core_event_et event; + uint32_t hw_thread_id; + uint32_t trig_id; + char stop_str[MCD_INFO_STR_LEN]; + char info_str[MCD_INFO_STR_LEN]; +} mcd_core_state_st; + + +/** + * struct mcd_rst_info_st - Structure type containing information about a + * particular reset class. + * + * @class_vector: Reset class vector which issues this reset. Exactly one bit + * may be set. + * @info_str: Description of the reset class. + * + * This structure type contains information about a particular reset class. Only + * a single bit of the 32 bit field @class_vector can be '1'. It represents the + * reset class for this particular reset. At target system level, there cannot + * be two objects of type mcd_rst_info_st bound to the same reset class. + */ +typedef struct mcd_rst_info_st { + uint32_t class_vector; + char info_str[MCD_INFO_STR_LEN]; +} mcd_rst_info_st; + + +/** + * struct mcd_chl_st - Structure type containing information about + * communication channels. + * + * @chl_id: Channel ID. + * @type: Type of the requested channel. + * @attributes: Attributes the requested channel has to provide. + * @max_msg_len: Maximum message length (e.g. size of the message buffer as + * specified by @msg_buffer_addr). + * @msg_buffer_addr: Address of the message buffer for memory mapped channels. + * @prio: Channel priority for a prioritized channel. Range is from 0 + * (highest priority) to %MCD_CHL_LOWEST_PRIORITY. + * + * This structure type contains information about the setup of a communication + * channel and about its properties. + */ +typedef struct mcd_chl_st { + uint32_t chl_id; + mcd_chl_type_et type; + mcd_chl_attributes_et attributes; + uint32_t max_msg_len; + mcd_addr_st msg_buffer_addr; + uint8_t prio; +} mcd_chl_st; + + +/** + * struct mcd_trace_info_st - Structure type containing information about a + * trace. + * + * @trace_id: ID of this trace source, ID 0 is reserved. This ID is + * used to identify the trace by all trace related f + * @trace_name: Trace source name. + * @trace_type: Type of this trace. + * @trace_format: Used trace data format. + * @trace_modes: Possible modes of this trace (OR'ed bitmask). + * @trace_no_timestamps: Is set if the target has no global "time" concept. It + * may still provide clock cycle information. + * @trace_shared: Is set if the trace buffer used by this trace is shared + * with other traces. + * @trace_size_is_bytes: Is set when the tracebuffer size (in + * mcd_trace_state_st) is defined in bytes instead of + * frames. + * + * This structure type contains information about a trace. + */ +typedef struct mcd_trace_info_st { + uint32_t trace_id; + char trace_name[MCD_INFO_STR_LEN]; + mcd_trace_type_et trace_type; + mcd_trace_format_et trace_format; + mcd_trace_mode_et trace_modes; + bool trace_no_timestamps; + bool trace_shared; + bool trace_size_is_bytes; +} mcd_trace_info_st; + + +/** + * struct mcd_trace_state_st - Structure type containing the trace state. + * + * @state: Trace state. + * @mode: Trace buffer mode. + * @autoarm: Trace's ARM/OFF state follows core run state. + * @wraparound: Set if the frame counter has wrapped around (in FIFO + * mode) or overflowed (in PIPE mode). + * @frames: Number of valid trace frames in the buffer. + * @count: Counts frames, but is not reset due to a wraparound if + * running in FIFO mode (serves as progress indicator). + * @size: Maximum size of trace (frames or bytes). + * @trigger_delay: Trigger delay. Input has the same unit as @size (frames + * or bytes). Output is the actually elapsed number of + * frames. + * @timestamp_accuracy: Accuracy of timestamping in percent (0 to 100). Higher + * values indicate more accurate timestamps. + * @timestamp_is_time: Set when timestamp is a time value (in picoseconds). + * Otherwise it represents clock cycles. + * @options: Implementation specific options. + * @modified: Set on return from mcd_set_trace_state_f when + * implementation could not exactly match requests.. + * @info_str: Additional information about the trace (only special + * state information). + * + * This structure type contains information about the trace state. + * + * Note that the additional information provided by @info_str is no repetition + * of the general trace state provided by @state. + */ +typedef struct mcd_trace_state_st { + mcd_trace_state_et state; + mcd_trace_mode_et mode; + bool autoarm; + bool wraparound; + uint64_t frames; + uint64_t count; + uint64_t size; + uint64_t trigger_delay; + uint8_t timestamp_accuracy; + bool timestamp_is_time; + uint32_t options; + bool modified; + char info_str[MCD_INFO_STR_LEN]; +} mcd_trace_state_st; + + +/** + * struct mcd_trace_data_core_st - Structure type containing simple core trace + * data. + * + * @timestamp: Timestamp of this cycle (picoseconds or clock cycles). + * @marker: Markers for this cycle. + * @cycle: Basic cycle type. + * @addr: Address. + * @data: Data (code length for program flow). + * @data_width: Width of data (in bytes), zero if @data_mask is used. + * @data_mask: Data bitmask, set bits indicate that the related byte in @data + * is valid. Zero if @data_width is used. + * @source: Additional source information (hardware thread ID, bus + * initiator, etc. + * @aux_info: Auxiliary information, e.g. endianess, burst information or core + * execution mode. + * + * This structure type contains simple trace data of cores and buses. + */ +typedef struct mcd_trace_data_core_st { + uint64_t timestamp; + mcd_trace_marker_et marker; + mcd_trace_cycle_et cycle; + mcd_addr_st addr; + uint64_t data; + uint8_t data_width; + uint8_t data_mask; + uint16_t source; + uint32_t aux_info; +} mcd_trace_data_core_st; + + +/** + * struct mcd_trace_data_event_st - Structure type containing logic analyzer + * trace data. + * @timestamp: Timestamp of this cycle (either picoseconds or clock cycles). + * @marker: Markers for this cycle. + * @data: User data, array of 256 bits. + * LSB of data[0] represents channel0. + * + * This structure type contains "logic analyzer"-like trace data (256 channels). + */ +typedef struct mcd_trace_data_event_st { + uint64_t timestamp; + mcd_trace_marker_et marker; + uint32_t data[8]; +} mcd_trace_data_event_st; + + +/** + * struct - Structure type containing statistic counter data. + * + * @timestamp: Timestamp of this cycle (either picoseconds or clock cycles). + * @marker: Markers for this cycle. + * @count: Array of 8 statistic counters ('-1' represents an invalid value). + * + * This structure type contains "logic analyzer"-like trace data (8 channels). + */ +typedef struct mcd_trace_data_stat_st { + uint64_t timestamp; + mcd_trace_marker_et marker; + uint64_t count[8]; +} mcd_trace_data_stat_st; + + +/** + * DOC: Target Initialization API + * + * API initialization functions are dedicated to Target interface initialization + * and closure. They allow to initialize the interaction between a tool and a + * target, as well as clean-up connections before closure. + */ + + +/** + * mcd_initialize_f() - Function initializing the interaction between a + * tool-side implementation and target-side implementation. + * + * @version_req: [in] MCD API version as requested by an upper layer. + * @impl_info: [out] Information about the implementation of the MCD API + * implementation. + * + * This function returns the version and vendor information for a particular + * implementation of the MCD API in order to initialize the interaction between + * a tool and a target-side implementation. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if target implementation is incompatible. + */ +mcd_return_et mcd_initialize_f(const mcd_api_version_st *version_req, + mcd_impl_version_info_st *impl_info); + + +/** + * mcd_exit_f() - Function cleaning up all core and server connections from a + * tool. + * + * This function allows to perform some cleanup functionality for all core + * connections to a particular debugger before closing the connections. + */ +void mcd_exit_f(void); + + +/** + * DOC: Server Connection API + * + * Server-connection API functions are used to setup a connection between a tool + * and a target through a target server. They allow to locate a target server + * open or close a connection to a target server. They also allow to retrieve + * and change a target server configuration. + */ + + +/** + * mcd_qry_servers_f() - Function returning a list of available servers. + * + * @host: [in] String containing the host name. + * @running: [in] Selects between running and installed servers. + * @start_index: [in] Start index of the queried servers. This refers to an + * internal list of the target side implementation. + * @num_servers: + * * [in] The number of queried servers starting from the defined + * @start_index. If it is set to '0', no server descriptions are returned but + * the number of all available servers. + * * [out] The number of returned servers. In case the input value of + * @num_servers is '0', this is the number of all available servers. + * @server_info: [out] Server information. This is an array allocated by the + * calling function. + * + * This function returns a list of available (running or installed) servers. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @start_index is equal or larger than the number of + * available servers. + * - %MCD_ERR_CONNECTION if query failed. + */ +mcd_return_et mcd_qry_servers_f(const char *host, bool running, + uint32_t start_index, uint32_t *num_servers, + mcd_server_info_st *server_info); + + +/** + * mcd_open_server_f() - Function opening the connection to a server on a host + * computer. + * + * @config_string: [in] Allows the configuration of the server connection by a + * character string. Delimiters are blanks, tabs and line + * breaks. Value strings are always enclosed with "double + * quotes". Bool values can be "TRUE" or "FALSE" (both in + * small letters). + * @system_key: [in] A server is claimed by this key when being opened. + * @server: [out] Pointer to the server connection instance. In contrast + * to the MCD API's usual calling scheme, the target has to + * allocate the object the pointer refers to. + * + * Pre-defined @config_string string parameters: + * + * - McdHostName= : Optional host name. Default value is + * "localhost". + * - McdServerName= : Name of the server to connect to. + * - McdSystemInstance= : Name of the simulation system instance this + * server is associated with. + * - McdServerKey= : Static key for this specific server. + * - McdExitIfLastClient : If mcd_close_server_f() is called for the + * last client connection, the server will terminate. + * + * Additional pre-defined string parameters for real hardware: + * + * - McdAccHw= : Restricts this server to connect to + * devices via a specific access hardware as determined by the string. + * - McdAccHw.Frequency= : Decimal (32 bit) value setting the + * frequency of the physical I/F (e.g. according to IEEE 1149.1) + * - McdAccHw.PostRstDelay= : Delay [microseconds] after reset before + * first interaction with the device is allowed. + * - McdAccHw.Device="" : Description of connected device. + * - McdAccHw.DeviceId= : Device ID (e.g. IEEE 1149.1 ID) of + * connected device. + * - McdAccHw.AutoDetect= : If set to "TRUE" the access HW detects + * the device (DeviceId and Device will be ignored). + * + * Interactive Server Connection Setup + * + * If a server(s) is running, mcd_open_server_f() can be called with an empty or + * NULL pointer @config_string. Then it connects to the first possible + * simulation system or, for real hardware, access hardware path. A second call + * (while the first server is still open) will open the second possible + * simulation system or access hardware path and so on. In order to restrict the + * potential list of connections to a server, "McdServerName" (and + * "McdServerKey") can be optionally provided with @config_string. + * + * mcd_qry_server_config_f() returns the complete configuration string for a + * server/device connection. This allows storing this configuration to avoid an + * interactive server connection setup for the next debug session. This is in + * particular useful for Real HW multi device systems in order to connect the + * devices step by step. + * + * Server and System Keys + * + * A server can optionally require a key for access (\c config_string parameter + * "McdServerKey"). This allows for example to prevent an unauthorized access to + * a test stand which might cause damage. A system key additionally allows to + * dynamically claim a server or to prevent several users from unintentionally + * accessing the same system at the same time through a specific set of servers. + * + * A key can be a password string or a sequence of decimal or hexadecimal + * numbers separated by whitespaces. + * + * This function opens the connection to a server on a host computer and updates + * the internal core information data base. It contains the information about + * all cores of devices which are simulated on the host computer or which are + * accessible on real silicon through a specific tool access hardware to the + * host. This data base can then be queried at system, device and core level. + * + * For real hardware devices, a server connection needs to be opened for each + * access hardware. This allows individual control of the access parameters. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CONNECTION if server connection failed. + */ +mcd_return_et mcd_open_server_f(const char *system_key, + const char *config_string, + mcd_server_st **server); + + +/** + * mcd_close_server_f() - Function closing the connection to a debug server on a + * host computer. + * + * @server: [in] Pointer to the server connection instance of the opened server. + * + * This function closes the connection to an opened debug server on a host + * computer. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CONNECTION if closing the server connection failed. + */ +mcd_return_et mcd_close_server_f(const mcd_server_st *server); + + +/** + * mcd_set_server_config_f() - Function changing the configuration of an open + * debug server. + * + * @server: [in] Pointer to the server connection instance of the + * opened server. + * @config_string: [in] String to configure the server or access hardware + * device. + * + * This function allows to change the configuration of an open server. Note that + * McdHostName, McdServerName and McdSystemInstance can't be changed with this + * function. When the @config_string contains such parameter which can't be + * changed or parameters which can't be changed to the requested value (e.g. new + * McdAccHw.Frequency not supported by the Access HW), these parameters will be + * ignored or e.g. the closest possible value will be chosen by the + * implementation. This behavior allows to use the same config strings/files for + * mcd_set_server_config_f() as for mcd_open_server_f(). The tool should always + * read back the actual config parameter values with mcd_qry_server_config_f(). + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CONNECTION if configuration of the server or access hardware + * device failed. + */ +mcd_return_et mcd_set_server_config_f(const mcd_server_st *server, + const char *config_string); + + +/** + * mcd_qry_server_config_f() - Function retrieving the configuration string of + * a debug server. + * + * @server: [in] Pointer to the server connection instance. + * @max_len: + * * [in] Maximum length of @config_string (as allocated by the calling + * function). + * * [out] Actual length required by the returned configuration string. + * @config_string: [out] String describing the configuration of the server or + * the access hardware device. + * + * This function retrieves the configuration string of an opened + * debug server. + * + * The string can be used to retrieve the configuration of a server + * for the following cases: + * - Server has been opened without setting "McdServerName" via @config_string. + * - Server has been configured with a server specific proprietary tool. + * + * Calling mcd_qry_server_config_f() with @max_len being a NULL pointer returns + * the required string length for @config_string. The returned length includes + * the terminating zero. This retrieved configuration can be stored by an MCD + * based tool in order to configure the server connection of the next session. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CONNECTION if server connection could not be accessed. + * - %MCD_ERR_RESULT_TOO_LONG if requested configuration string is longer than + * @max_len. + */ +mcd_return_et mcd_qry_server_config_f(const mcd_server_st *server, + uint32_t *max_len, + char *config_string); + + +/** + * DOC: Target System Features API + * + * Target System Features API functions allow to query the core connection + * information according to several cases: for a specified number of systems; + * for a specified number of devices of a particular system or for a specified + * number of cores of a system (or device). This API subset also allows querying + * the available modes of a specific core. + */ + + +/** + * mcd_qry_systems_f() - Function querying the core connection information of a + * specified number of systems. + * + * @start_index: [in] Start index of the queried systems. This refers to an + * internal list of the target side implementation. + * @num_systems: + * * [in] The number of queried systems starting from the defined @start_index. + * If it is set to '0', no core connection information is returned but the + * number of available systems. + * * [out] : The number of systems the core connection info was returned for. In + * case the input value of @num_systems is '0', this is the number of all + * available systems. + * @system_con_info: [out] Core connection information of the requested systems. + * This is an array allocated by the calling function. + * + * This function queries for the core connection information of a specified + * number of systems. The returned core_con_info data are distinguished for + * different systems only by the name of the system. If @num_systems is set to + * '0', the function call returns the number of all available systems. + * + * Only the following information of @system_con_info shall be set by the + * target: + * + * - system_key + * - system + * - system_instance + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @start_index is equal or larger than the number of + * available systems. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_systems_f(uint32_t start_index, uint32_t *num_systems, + mcd_core_con_info_st *system_con_info); + + +/** + * mcd_qry_devices_f() - Function querying the core connection information of a + * specified number of devices of a system. + * + * @system_con_info: [in] Core connection information of the system the devices + * are queried from. + * @start_index: [in] Start index of the requested devices. This refers to + * an internal list of the target side implementation. + * @num_devices: + * * [in] The number of queried devices (e.g. simulated on or connected to this + * host computer) starting from the defined @start_index. If it is set to '0', + * no core connection information is returned but the number of all available + * devices. + * * [out] The number of devices the core connection information was returned + * for. In case the input value of @num_devices is '0', this is the number of + * all available devices for the selected system. + * @device_con_info: [out] Core connection information of the requested devices. + * This is an array allocated by the calling function. + * + * This function queries for the core connection information of a specified + * number of devices of a particular system. If @num_devices is set to '0', the + * function call returns the number of all available devices for the system. + * + * Only the system and system_instance information of system_con_info are used + * for system selection. + * + * Only the following information of @device_con_info shall be set by the + * target: + * + * - host + * - server_port + * - system_key + * - device_key (zero length string if no device key) + * - system + * - system_instance (zero length string for Real HW) + * - acc_hw (for Real HW) + * - device_type + * - device + * - device_id + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @start_index is equal or larger than the number of + * available devices. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_devices_f(const mcd_core_con_info_st *system_con_info, + uint32_t start_index, uint32_t *num_devices, + mcd_core_con_info_st *device_con_info); + + +/** + * mcd_qry_cores_f() - Function querying the core connection information of a + * specified number of cores of a system/device. + * + * @connection_info: [in] Core connection information of the system or device + * the cores are queried from. + * @start_index: [in] Start index of the requested cores. This refers to an + * internal list of the target side implementation. + * @num_cores: + * * [in] The number of queried cores starting from the defined @start_index. If + * it is set to '0', no core connection information is returned but the number + * of all available cores. + * * [out] The number of cores the core connection information is returned for. + * In case the input value of @num_cores is '0', this is the number of all + * available cores for the selected system or device. + * @core_con_info: [out] Core connection information of the requested cores. + * This is an array allocated by the calling function. + * + * This function queries the core connection information of a specified number + * of cores of a system/device. + * + * Only the system and system_instance information of connection_info are used + * for system selection. + * + * For selecting a specific device, the following information of + * @connection_info is used: + * + * - host + * - server_port + * - system_key + * - device_key (zero length string if no device key) + * - system + * - system_instance (zero length string for Real HW) + * - acc_hw (for Real HW) + * - device_type + * - device + * - device_id + * + * If device and acc_hw are given for Real HW, only the cores of this specific + * device will be returned. + * + * The output parameter @core_con_info shall contain the complete + * mcd_core_con_info_st information except from device_key. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @start_index is equal or larger than the number of + * available cores. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_cores_f(const mcd_core_con_info_st *connection_info, + uint32_t start_index, uint32_t *num_cores, + mcd_core_con_info_st *core_con_info); + + +/** + * mcd_qry_core_modes_f() - Function querying the available modes of a core. + * + * @core: [in] A reference to the core the calling function addresses. + * @start_index: [in] Start index of the requested modes. This refers to an + * internal list of the target side implementation. + * @num_modes: + * * [in] The number of queried core modes starting from the defined + * @start_index. If it is set to '0', no core modes are returned but the + * number of all available core modes. + * * [out] : The number of returned core modes. In case the input value of + * @num_modes is '0', this is the number of all available core modes for the + * selected core. + * @core_mode_info: [out] : Core mode information of the requested core. This is + * an array allocated by the calling function. + * + * This function queries the available modes of a specific core. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @start_index is equal or larger than the number of + * available core modes. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_core_modes_f(const mcd_core_st *core, + uint32_t start_index, uint32_t *num_modes, + mcd_core_mode_info_st *core_mode_info); + + +/** + * DOC: Core Connection API + * + * Core Connection API functions allow the management of a connection to a core, + * such as: opening or closing a specific core connection ; retrieving detailed + * error and/or event information after an API call ; as well as querying + * payload size for a transaction list. + */ + + +/** + * mcd_open_core_f() - Function opening a core connection. + * + * @core_con_info: [in] Unambiguous core information (e.g. from + * mcd_qry_cores_f()). + * @core: [out] Pointer to the requested core connection instance (In + * contrast to the API's usual scheme, the target has to + * allocate the object the pointer refers to). + * + * Note that device_key needs to be set in core_con_info in case of opening a + * locked device. + * + * This function opens a specific core connection. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @core_con_info is ambiguous. + * - %MCD_ERR_DEVICE_LOCKED if the requested device is locked. + * - %MCD_ERR_CONNECTION if opening the core connection failed. + */ +mcd_return_et mcd_open_core_f(const mcd_core_con_info_st *core_con_info, + mcd_core_st **core); + + +/** + * mcd_close_core_f() - Function closing a core connection. + * + * @core: [in] Pointer to the core connection instance of the core to close. + * + * This function closes a specific core connection. + * + * Allowed error codes: + * + * * - %MCD_ERR_NONE if successful. + * * - %MCD_ERR_CONNECTION if closing the core connection failed. + */ +mcd_return_et mcd_close_core_f(const mcd_core_st *core); + + +/** + * mcd_qry_error_info_f() - Function allowing the access to detailed error + * and/or event information after an API call. + * + * @core: [in] A reference to the core the calling function addresses. + * This parameter can be NULL if the error occurred at a function + * without a parameter of type mcd_core_st. + * @error_info: [out] Pointer to a structure containing the detailed error/event + * information. + * + * Almost all MCD API functions return a value of type mcd_return_et. This is an + * enumeration type informing the calling function how to react on the API + * function call's results. If an error occurred, the calling function has to + * call this function in order to obtain details about the error and/or event + * which occurred during the previous call and in order to gain further details + * on it. + * + */ +void mcd_qry_error_info_f(const mcd_core_st *core, + mcd_error_info_st *error_info); + + +/** + * mcd_qry_device_description_f () - Function retrieving the file information of + * an IP-XACT description of the addressed + * component. + * + * @core: [in] A reference to the core the calling function addresses. + * @url: [out] A pointer to the string containing the URL pointing to the + * IP-XACT description is returned through this parameter. Space + * for the URL must be reserved by the caller. The string returned + * must be null terminated except if it is too large to fit the + * buffer. If called with a null pointer then the required buffer + * size will be returned in the url_length parameter. + * @url_length: [in] Pointing to the size of the buffer allocated by the caller. + * @url_length: [out] Pointing to the size of the URL returned excluding the + * terminating '\\0' character. When called with url=0 returns the + * size of the buffer required including the terminating '\\0' + * character. + * + * This functions can be used to request the URL where an IP-XACT + * description describing a system can be acquired. The most common for + * is to use a URL starting with "file://..." referring to a local + * file where the description is stored in the local filesystem. This + * is also the only mandatory URI scheme ("protocol") which must be + * supported in every tool. Other possible options are URLs starting + * with "http://..." or "ftp://...". URLs might either point to the + * MCD server itself, but could also point to locations on other + * servers. + * + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if URL could not be provided. + */ +mcd_return_et mcd_qry_device_description_f(const mcd_core_st *core, + char *url, uint32_t *url_length); + + +/** + * mcd_qry_max_payload_size_f() - Function querying the maximum payload size + * for a transaction list. + * + * @core: [in] A reference to the core the calling function addresses. + * @max_payload: [out] Maximum (and optimum) supported payload size for a + * transaction list. + * + * Different systems will support a different maximum in transaction list + * payload sizes. The payload is the net number of bytes that are read or + * written. This function queries the maximum payload size for a transaction + * list. Since a tool needs to be able to deal with smaller payload sizes, the + * only reason to use larger payloads is an improved performance. In order to + * achieve this performance, it is recommended that @max_payload is equal to the + * payload allowing the optimum performance. + * @max_payload then should be obeyed by the sent transaction lists. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_max_payload_size_f(const mcd_core_st *core, + uint32_t *max_payload); + + +/** + * mcd_qry_input_handle_f() - Function querying the input handle for the + * connection. + * + * @core: [in] A reference to the core the calling function addresses. + * @input_handle: [out] Input handle or -1 if handle not defined. + * + * Fast and efficient reaction on target system events with a single threaded + * application requires that the application can wait for user input or + * asynchronous activity from the target. Obtaining the handle used for the + * communication to the target (usually a socket) allows the application to wait + * for activity there without frequent polling. If the communication is not done + * by sockets then there may be no such handle. + * + * Allowed error codes: + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_input_handle_f(const mcd_core_st *core, + uint32_t *input_handle); + + +/** + * DOC: Target Memory Access API + * + * Target Memory Access API functions are related to the configuration + * of memories. They allow retrieving memory spaces for a particular component, + * or memory blocks of a specified memory space. + */ + + +/** + * mcd_qry_mem_spaces_f() - Function querying the available memory spaces for a + * particular component. + * + * @core: [in] A reference to the core the calling function addresses. + * @start_index: [in] Start index of the requested memory spaces. This refers to + * an internal list of the target side implementation. + * @num_mem_spaces: + * * [in] Number of memory spaces, information is requested of. If it is set to + * '0', no memory space information is returned but the number of all + * available memory spaces for the selected core. + * * [out] : The number of returned memory spaces. In case the input value of + * @num_mem_spaces is '0', this is the number of all available memory spaces + * for the selected core. + * @mem_spaces: [out] Memory space information. This is an array allocated by + * the calling function. + * + * There can be various memory spaces visible to a core depending on its + * architecture. For Harvard architectures these can be "program" and "data", + * for DSP architecture these can be "P"/"X"/"Y", etc. This function queries all + * memory spaces available for a particular target core. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_NO_MEM_SPACES if no memory spaces are defined for this core. + */ +mcd_return_et mcd_qry_mem_spaces_f(const mcd_core_st *core, + uint32_t start_index, + uint32_t *num_mem_spaces, + mcd_memspace_st *mem_spaces); + +/** + * mcd_qry_mem_blocks_f() - Function querying the available memory blocks of a + * specified memory space. + * + * @core: [in] A reference to the core the calling function addresses. + * @mem_space_id: [in] The ID of the memory space the calling function queries + * the memory block information from. + * @start_index: [in] Start index of the requested memory blocks. This refers + * to an internal list of the target side implementation. + * @num_mem_blocks: + * * [in] Number of memory blocks, information is requested of. If it is set to + * '0', no memory block information is returned but the number of all + * available memory blocks for the selected memory. + * * [out] : Number of returned memory blocks. In case the input value of + * @num_mem_blocks is '0', this is the number of all available memory blocks + * for the selected memory space. + * @mem_blocks: [out] Memory block information. This is an array allocated by + * the calling function. + * + * There can be various memory blocks within a particular memory space of a + * core. The memory blocks define the layout of the memory space. Memory blocks + * can be hierarchical in nature, and this query function returns information + * about all available memory blocks in the memory space. Memory blocks with the + * same parent must not overlap. This call returns existing memory blocks only. + * If a target side implementation supports memory block descriptions, the + * calling function may assume that memory which does not belong to any memory + * block is not addressable. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_NO_MEM_BLOCKS if no memory blocks are defined for this memory + * space. + */ +mcd_return_et mcd_qry_mem_blocks_f(const mcd_core_st *core, + uint32_t mem_space_id, uint32_t start_index, + uint32_t *num_mem_blocks, + mcd_memblock_st *mem_blocks); + +/** + * mcd_qry_active_overlays_f() - Function querying the active (swapped-in) + * overlays at the current time. + * + * @core: [in] A reference to the core the calling function + * addresses. + * @start_index: [in] Start index of the requested active memory + * overlays. This refers to an internal list of the target + * side implementation. + * @num_active_overlays: + * * [in] Number of active memory overlays, information is requested of. If it + * is set to '0', no active memory overlay information is returned but the + * number of all available active memory overlays for the selected core. + * * [out] Number of returned active memory overlays. In case the input value of + * @num_active_overlays is '0', this is the number of all available active + * memory overlays for the selected core. + * @active_overlays: [out] Active memory overlay information. This is an array + * allocated by the calling function. + * + * This function is called when the caller wants to retrieve the list of active + * memory overlays. This is typically done when a breakpoint is hit. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_OVERLAYS if retrieving active memory overlay information failed. + */ +mcd_return_et mcd_qry_active_overlays_f(const mcd_core_st *core, + uint32_t start_index, + uint32_t *num_active_overlays, + uint32_t *active_overlays); + + +/** + * DOC: Target Register Access API + * + * Target Register Access API functions are related to the access and + * configuration of registers. Registers in an IP may be of the following two + * types: + * + * - Internal IP registers: These registers are internal to an IP and cannot be + * accessed by other system components connected to the bus. Special means + * must be provided in order to make these registers visible to the external + * tools such as debugging and profiling tools. An example of a mechanism + * commonly used to expose such internal registers of an IP to external tools + * is the use of scan chains and an IP specific TAP controller whose data + * registers are mapped to a few of these internal registers. These registers + * must be accessed by the debugging and profiling tools using their ID, which + * need to be unique within the scope of a particular instance of an IP. + * + * - Memory Mapped registers: These registers are mapped to memory addresses + * which are an offset to a base address belonging to that IP. They can + * therefore be accessed via the bus infrastructure using common memory + * addressing mechanisms. These registers may be accessed by the debugging and + * profiling tools using their ID, which must be unique within the scope of a + * particular instance of an IP. Alternatively, they may be accessed by + * external tools using their memory mapped addresses via the memory bus. + */ + + +/** + * mcd_qry_reg_groups_f() - Function querying the register groups defined for a + * particular component. + * + * @core: [in] A reference to the core the calling function addresses. + * @start_index: [in] Start index of the requested register groups. This refers + * to an internal list of the target side implementation. + * @num_reg_groups: + * * [in] Number of register groups, information is requested of. If it is set + * to '0', no register groups information is returned but the number of all + * available register groups for the selected core. + * * [out] Number of returned register groups. In case the input value of + * @num_reg_groups is '0', this is the number of all available register groups + * for the selected core. + * @reg_groups: [out] Register group information. This is an array allocated by + * the calling function. + * + * There can be various register groups defined for a core depending on its + * architecture. This function queries information about these register groups. + * + * The parameter @num_reg_groups is used as an input/output parameter. + * As input parameter it is set to the desired number of register groups. As + * output parameter it set to the actual number of register groups information + * is returned for in @reg_groups. + * If the target does not define any register groups, it is assumed that a + * virtual register group with ID 0 exists which contains all registers of the + * corresponding component. Then the information about this default 'virtual' + * register group has to be sent back as only register group information. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_NO_REG_GROUPS if no register groups are defined for this core. + */ +mcd_return_et mcd_qry_reg_groups_f(const mcd_core_st *core, + uint32_t start_index, + uint32_t *num_reg_groups, + mcd_register_group_st *reg_groups); + + +/** + * mcd_qry_reg_map_f() - Function querying the register information of a + * particular register group. + * + * @core: [in] A reference to the core the calling function addresses. + * @reg_group_id: [in] ID of the register group detailed register information is + * requested for. + * @start_index: [in] Start index of the requested registers. This refers to an + * internal list of the target side implementation. + * @num_regs: + * * [in] Number of registers, information is requested of. If it is set to '0', + * no register information is returned but the number of all available + * registers within for the selected register group. + * * [out] Number of returned registers. In case the input value of @num_regs is + * '0', this is the number of all available register for the selected register + * group. + * @reg_info: [out] Register information. This is an array allocated by the + * calling function. + * + * There can be various register groups defined for a core depending on its + * architecture. Within each register group there can be many registers. This + * function allows the user to query information about the registers contained + * within a register group. Information all registers which have to be exposed + * to the debug environment have to be returned as a result of such a query. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_REG_GROUP_ID if no register group with this ID is available + * for this core. + */ +mcd_return_et mcd_qry_reg_map_f(const mcd_core_st *core, uint32_t reg_group_id, + uint32_t start_index, uint32_t *num_regs, + mcd_register_info_st *reg_info); + + +/** + * mcd_qry_reg_compound_f() - Function querying the component registers of a + * compound register + * + * @core: [in] A reference to the core the calling function + * addresses. + * @compound_reg_id: [in] ID of the compound register component register IDs are + * queried for. + * @start_index: [in] Start index of the requested component registers. This + * refers to an internal list of the target side + * implementation. + * @num_reg_ids: + * * [in] Number of component registers the ID is requested of. If it is set to + * '0', no component register IDs are returned but the number of all available + * component register for the selected compound register. + * * [out] : Number of returned component registers. In case the input value of + * @num_reg_ids is '0', this is the number of all available component + * registers for the selected compound register. + * @reg_id_array: [out] Component register IDs. This is an array allocated by + * the calling function. + * + * Registers within a target component may be composed of several simple + * registers. These are by definition called "compound registers". This function + * allows a user to query information about the registers contained within a + * particular compound register. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_REG_NOT_COMPOUND if no compound register with this ID is available + * for this core. + */ +mcd_return_et mcd_qry_reg_compound_f(const mcd_core_st *core, + uint32_t compound_reg_id, + uint32_t start_index, + uint32_t *num_reg_ids, + uint32_t *reg_id_array); + + +/** + * DOC: Target Trigger Setup API + * + * Target Trigger Setup API functions allow management of triggers, such as + * creation, activation, deletion or trigger status inquiry. Typical triggers + * are breakpoints, but the API allows definition of complex triggers, as well + * as complex trigger conditions. Triggers can be managed individually but also + * as a trigger set defined for a core. + */ + + +/** + * mcd_qry_trig_info_f() - Function querying information about trigger + * capabilities. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig_info: [out] Information about supported triggers. + * + * This function queries information about trigger capabilities implemented + * in a target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if trigger capabilities could not be retrieved. + */ +mcd_return_et mcd_qry_trig_info_f(const mcd_core_st *core, + mcd_trig_info_st *trig_info); + + +/** + * mcd_qry_ctrigs_f() - Function querying information about custom triggers. + * + * @core: [in] A reference to the core the calling function addresses. + * @start_index: [in] Start index of the requested custom triggers. This refers + * to an internal list of the target side implementation. + * @num_ctrigs: + * * [in] Number of custom triggers, information is requested of. If it is set + * to '0', no custom trigger information is returned but the number of all + * available custom triggers for the selected core. + * * [out] : Number of returned custom triggers. In case the input value of + * @num_ctrigs is '0', this is the number of all available custom triggers for + * the selected core. + * @ctrig_info: [out] Custom trigger information. This is an array allocated by + * the calling function. + * + * This function queries information about custom triggers of a component as + * well as the number of available custom triggers. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if custom trigger ID does not exist. + */ +mcd_return_et mcd_qry_ctrigs_f(const mcd_core_st *core, uint32_t start_index, + uint32_t *num_ctrigs, + mcd_ctrig_info_st *ctrig_info); + +/** + * mcd_create_trig_f() - Function allowing the creation of a new trigger. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig: + * * [in] Pointer to the structure containing information about the trigger + * object to be created. + * * [out] : Members of the structure may be modified by the function. In this + * case the modified member of the trigger structure as well as the modified + * members are set. + * @trig_id: [out] Unique ID for the newly created trigger returned by the API + * implementation. A value of '0' indicates that the breakpoint is + * set, but cannot be identified by an ID. Removing such breakpoints + * is only possible by calling mcd_remove_trig_set_f(). + * + * This function allows a user to create a new trigger. If the exact trigger + * cannot be created, an approximate trigger is created instead and the modified + * member of the trigger structure is set. + * + * The void pointer @trig usually points to a standard trigger structure like + * mcd_trig_simple_core_st or mcd_trig_complex_core_st. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_CREATE if trigger could not be created. + */ +mcd_return_et mcd_create_trig_f(const mcd_core_st *core, void *trig, + uint32_t *trig_id); + + +/** + * mcd_qry_trig_f() - Function querying the contents of a trigger. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig_id: [in] ID of the trigger the user queries. + * @max_trig_size: [in] Maximum size of the structure in bytes as expected by + * the calling function. + * @trig: [out] Pointer to the structure receiving the information about + * the trigger object. The structure is allocated by the calling + * function. + * + * This function allows the user to query the contents of a trigger. + * The @max_trig_size parameter is set to the maximum size of + * the trigger structure the user expects in bytes. + * + * The void pointer trig usually points to a standard trigger + * structure like mcd_trig_simple_core_st or mcd_trig_complex_core_st. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_RESULT_TOO_LONG if requested trigger is larger than + * @max_trig_size. + * - %MCD_ERR_TRIG_ACCESS if trigger could not be returned for any other + * reason. + */ +mcd_return_et mcd_qry_trig_f(const mcd_core_st *core, uint32_t trig_id, + uint32_t max_trig_size, void *trig); + + +/** + * mcd_remove_trig_f() - Function allowing a user to delete a particular trigger + * from a trigger set. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig_id: [in] ID of the trigger the user wants to delete. + * + * This function allows the user to delete a particular trigger from a trigger + * set. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if trigger could not be accessed for deletion. + */ +mcd_return_et mcd_remove_trig_f(const mcd_core_st *core, uint32_t trig_id); + + +/** + * mcd_qry_trig_state_f() - Function allowing a user to query the trigger states + * from the target. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig_id: [in] ID of the trigger, the tool queries the state for. + * @trig_state: [out] Queried Trigger state. The structure is allocated by the + * calling function. + * + * This function allows a user to query the status of a single trigger. + * Note that mcd_qry_trig_set_state_f() needs to be called before to sample + * the trigger state. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if trigger could not be accessed. + */ +mcd_return_et mcd_qry_trig_state_f(const mcd_core_st *core, uint32_t trig_id, + mcd_trig_state_st *trig_state); + + +/** + * mcd_activate_trig_set_f() - Function allowing a user to activate a trigger + * set on the target. + * + * @core: [in] A reference to the core the calling function addresses. + * + * This function downloads the current trigger set to the hardware in order to + * activate it. If the trigger set is unchanged since the last call of this + * function, it will just arm the triggers again. + * + * This function is only needed to activate triggers on the fly (while the + * target is running) and in a consistent way - if supported by the target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if trigger set could not be activated. + */ +mcd_return_et mcd_activate_trig_set_f(const mcd_core_st *core); + + +/** + * mcd_remove_trig_set_f() - Function allowing a user to delete a trigger set. + * + * @core: [in] A reference to the core the calling function addresses. + * + * This function allows a user to delete a trigger set for a particular core. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if trigger set could not be removed. + */ +mcd_return_et mcd_remove_trig_set_f(const mcd_core_st *core); + + +/** + * mcd_qry_trig_set_f() - Function querying the contents of a trigger set. + * + * @core: [in] A reference to the core the calling function addresses. + * @start_index: [in] Start index of the requested triggers. This refers to an + * internal list of the target side implementation. + * @num_trigs: + * * [in] The number of queried triggers starting from the defined + * @start_index. If it is set to '0', no triggers are returned but the number + * of all available triggers of the trigger set. + * * [out] The number of returned triggers. In case the input value of + * @num_trigs is '0', this is the number of all available triggers of this + * core's trigger set. + * @trig_ids: [out] List of trigger IDs set in the target. This is an array + * allocated by the calling function. + * + * This function queries information about the current state of the trigger set + * of a target core. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if trigger set could not be queried. + */ +mcd_return_et mcd_qry_trig_set_f(const mcd_core_st *core, uint32_t start_index, + uint32_t *num_trigs, uint32_t *trig_ids); + + +/** + * mcd_qry_trig_set_state_f() - Function querying the state of a trigger set. + * + * @core: [in] A reference to the core the calling function addresses. + * @trig_state: [out] Information about the current state of the trigger set. + * + * This function queries information about the current state of the trigger set + * of a target core. It will consistently sample the state of all triggers in + * the set. This is in particular necessary for Real HW targets. The individual + * triggers can then be queried with \ref mcd_qry_trig_state_f(). + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TRIG_ACCESS if state of the trigger set could not be queried. + */ +mcd_return_et mcd_qry_trig_set_state_f(const mcd_core_st *core, + mcd_trig_set_state_st *trig_state); + + +/** + * DOC: Target Execution Control API + * + * Target Execution Control API functions allow control of the execution, such + * as run, stop and step. They allow querying the state of a core as well as the + * execution time of the target. The API also allows execution of commands + * grouped as transaction lists. + * + */ + + +/** + * mcd_execute_txlist_f() - Function executing a transaction list on the target. + * + * @core: [in] A reference to the core the calling function addresses. + * @txlist: [in] A pointer to the transaction list for execution. + * + * This function sends a transaction list to the target for execution and + * retrieves the result. It is blocking, so it is the responsibility of the tool + * to make sure that the execution time will be reasonable by creating a + * transaction list with an appropriate payload size. + * + * Note that multiple tools can issue transaction lists requests to the same + * core at the same time. + * + * In case of an error, the execution of the transaction list is immediately + * aborted. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_TXLIST_READ if execution of the transaction list aborted due to a + * specific read access. + * - %MCD_ERR_TXLIST_WRITE if execution of the transaction list aborted due to a + * specific write access. + * - %MCD_ERR_TXLIST_TX if execution of the transaction list aborted due to + * any other reason. + */ +mcd_return_et mcd_execute_txlist_f(const mcd_core_st *core, + mcd_txlist_st *txlist); + + +/** + * mcd_run_f() - Function starting execution on a particular core. + * + * @core: [in] A reference to the core the calling function addresses. + * @global: [in] Set to "TRUE" if all cores of a system shall start execution. + * Otherwise, starting execution of selected core only. + * + * This function causes the corresponding target core to begin execution. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if starting execution failed. + */ +mcd_return_et mcd_run_f(const mcd_core_st *core, bool global); + + +/** + * mcd_stop_f() - Function stopping execution on a particular core. + * + * @core: [in] A reference to the core the calling function addresses. + * @global: [in] Set to "TRUE" if all cores of a system shall stop + * execution. Otherwise, stopping execution of selected + * core only. + * + * This function causes the corresponding target core to stop execution. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if stopping execution failed. + */ +mcd_return_et mcd_stop_f(const mcd_core_st *core, bool global); + + +/** + * mcd_stop_f() - Function running a particular core until a defined time. + * + * @core: [in] A reference to the core the calling function addresses. + * @global: [in] Set to "TRUE" if all cores of a system shall start + * execution. Otherwise, starting execution of selected core + * only. + * @absolute_time: [in] Boolean value indicating whether the time parameter is + * absolute or not. + * @run_until_time: [in] The number of time units (picoseconds) until which the + * target core shall run. + * + * This function causes the corresponding target core to run for a defined time + * before it stops. If @absolute_time is "FALSE", @run_until_time is the value + * of the system timer that is associated with this core. This means it starts + * again from '0' for certain reset types, and it needs to be scaled depending + * on the crystal and PLL settings in order to determine a time value. If + * @absolute_time is "TRUE", @run_until_time is an absolute time in seconds. + * Usually, a simulation model can only support this case. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if execution failed. + */ +mcd_return_et mcd_run_until_f(const mcd_core_st *core, bool global, + bool absolute_time, uint64_t run_until_time); + +/** + * mcd_qry_current_time_f() - Function querying the current time of execution + * from the target system. + * + * @core: [in] A reference to the core the calling function addresses. + * @current_time: [out] The current number of time units (picoseconds) the + * target system has been running. + * + * This function returns the current execution time of the target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if querying for the time failed. + */ +mcd_return_et mcd_qry_current_time_f(const mcd_core_st *core, + uint64_t *current_time); + +/** + * mcd_step_f() - Function stepping a target core based on the particular step + * type. + * + * @core: [in] A reference to the core the calling function addresses. + * @global: [in] Set to "TRUE" if all cores of a system shall start + * execution. Otherwise, starting execution of selected core only. + * @step_type: [in] The unit, the stepping of the target core is based on. + * @n_steps: [in] The number of steps, the target core is stepped for. + * + * This function causes the corresponding target core to step based on the + * provided step type. + * + * Note that the function is blocking. It is the responsibility of the tool to + * call it with a reasonable number of steps. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if stepping the target core failed. + */ +mcd_return_et mcd_step_f(const mcd_core_st *core, bool global, + mcd_core_step_type_et step_type, uint32_t n_steps); + + +/** + * mcd_set_global_f() - Function enabling/disabling global stop and run + * activities on this core. + * + * @core: [in] A reference to the core the calling function addresses. + * @enable: [in] Set to "TRUE" if this core should perform global run or stop + * activities. + * + * This function enables or disables the effect of a global run and stop on this + * core. The default state is target specific. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful.\n + * - %MCD_ERR_GENERAL if enabling/disabling the global effect of execution + * functions failed. + */ +mcd_return_et mcd_set_global_f(const mcd_core_st *core, bool enable); + + +/** + * mcd_qry_state_f() - Function querying the execution state of a target core. + * + * @core: [in] A reference to the core the calling function addresses. + * @state: [out] The current execution state of the target core. + * + * This function queries the current execution state of a particular target + * core. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful.\n + * - %MCD_ERR_GENERAL if querying the execution state failed. + */ +mcd_return_et mcd_qry_state_f(const mcd_core_st *core, + mcd_core_state_st *state); + + +/** + * mcd_execute_command_f() - Function executing a command on the target + * platform. + * + * @core: [in] A reference to the core the calling function + * addresses. + * @command_string: [in] The command string. This is implementation + * specific. + * @result_string_size: [in] The maximum size of the result string. + * @result_string: [out] The result string allocated by the calling + * function. + * + * This function sends a command to the target platform and retrieves the result + * in the form of a string. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if executing the command failed. + */ +mcd_return_et mcd_execute_command_f(const mcd_core_st *core, + const char *command_string, + uint32_t result_string_size, + char *result_string); + + +/** + * DOC: Reset Control API + * + * Reset Control API functions allow querying information about the reset + * classes supported by the target system, as well as triggering one or more + * reset signals in parallel on the target system. + * + */ + + +/** + * mcd_qry_rst_classes_f() - Function querying information about reset classes + * supported by the target system. + * @core: [in] A reference to the core the calling function + * addresses. + * @rst_class_vector: [out] A 32 bit vector that defines the available reset + * classes. + * + * This function queries all available reset classes of the target system. Each + * bit of @rst_class_vector represents an available reset class. + * + * It is recommended that the strongest reset (e.g. power-on reset) is of class + * '0'. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if querying the reset classes failed. + */ +mcd_return_et mcd_qry_rst_classes_f(const mcd_core_st *core, + uint32_t *rst_class_vector); + + +/** + * mcd_qry_rst_class_info_f() - Function querying information about a particular + * reset class supported by the target system. + * + * @core: [in] A reference to the core the calling function addresses. + * @rst_class: [in] Reset class ID which refers to a bit in the 32-bit reset + * class vector as obtained by mcd_qry_rst_classes_f(). + * @rst_info: [out] Reference to an object of type mcd_rst_info_st containing + * detailed information about this reset class. + * + * This function queries more detailed information about a particular reset + * class of the target system. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if reset class does not exist. + * - %MCD_ERR_GENERAL if any other error occurred. + */ +mcd_return_et mcd_qry_rst_class_info_f(const mcd_core_st *core, + uint8_t rst_class, + mcd_rst_info_st *rst_info); + + +/** + * mcd_rst_f() - Function triggering one or more reset signals in parallel on + * the target system. + * + * @core: [in] A reference to the core the calling function + * addresses. + * @rst_class_vector: [in] Reset vector specifying the resets which shall be + * issued. + * @rst_and_halt: [in] Optionally halting the core if the reset changes the + * core state. + * + * This function triggers one or more reset signals in parallel on the target + * system. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if one or several reset classes do not exist. + * - %MCD_ERR_GENERAL if any other error occurred. + */ +mcd_return_et mcd_rst_f(const mcd_core_st *core, uint32_t rst_class_vector, + bool rst_and_halt); + + +/** + * DOC: Communication Channel API + * + * Communication channels allow the exchange of data between a tool and the + * target. A channel requested by the tool is specified by mcd_chl_st. This + * structure type contains information on the channel type and its attributes. + * The number of channels for each server of the MCD API is limited to + * MCD_CHL_NUM_MAX. A channel can be both uni- and bi-directional. It also may + * be memory-mapped and prioritized. In the latter case, the channel priority + * determines the sequence of communication transfers between the target and the + * connected tools. + * + * Note that there must never be two or more open channels of the same priority + * to a single target. In case of conflicts the channel will get the closest + * free priority. + */ + + +/** + * mcd_chl_open_f() - Function opening a communication channel between the host + * tool and the target. + * + * @core: [in] A reference to the targeted system, device or core. Here, member + * instance is allowed to be a null pointer for levels higher than core + * level. + * @channel: + * * [in] Requested channel setup. + * * [out] Accepted and at least for chl_id modified channel setup. Note that + * max_msg_len and prio can be changed as well if the requested values are not + * possible. + * + * This function opens a defined communication channel between a host side tool + * and a target. The addressed target is identified by a core reference. This + * function call allows to establish a communication channel between the host + * side tool and any hierarchical level of the targeted system (i.e. at system + * level, at device level or at core level). For this reason, this function call + * accepts core structures which have their member instance set to a null + * pointer for levels higher than core level. The target implementation actually + * needs to determine the targeted hierarchical level based on the member + * core_con_info of the core structure. The established channel is described by + * channel. Only a single debugger may be attached to a communication channel at + * a time. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CHL_TYPE_NOT_SUPPORTED if unsupported channel type was + * requested. + * - %MCD_ERR_CHL_TARGET_NOT_SUPPORTED if addressed target does not support + * communication channels. + * - %MCD_ERR_CHL_SETUP if channel setup is invalid or contains + * unsupported attributes. + */ +mcd_return_et mcd_chl_open_f(const mcd_core_st *core, mcd_chl_st *channel); + + +/** + * mcd_send_msg_f() - Function send a message using a specified communication + * channel. + * + * @core: [in] A reference to the targeted system, device or core. Here, + * member instance is allowed to be a null pointer for levels higher + * than core level. + * @channel: [in] Description of the addressed communication channel. + * @msg_len: [in] The number of bytes sent with this message. + * @msg: [in] Message buffer. + * + * This function sends a message using a defined communication channel between + * the host and the target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CHL_MESSAGE_FAILED if sending the message failed. + */ +mcd_return_et mcd_send_msg_f(const mcd_core_st *core, const mcd_chl_st *channel, + uint32_t msg_len, const uint8_t *msg); + + +/** + * mcd_receive_msg_f() - Function receiving a message using a specified + * communication channel. + * + * @core: [in] A reference to the targeted system, device or core. Here, for + * member instance is allowed to be a null pointer for levels higher + * than core level. + * @channel: [in] Description of the addressed communication channel. + * @timeout: [in] Number of time units (milliseconds) until function call times + * out. + * @msg_len: [in] Maximum number of bytes that can be fetched with this call. + * @msg_len: [out] Number of bytes that have been actually fetched with this + * call. + * @msg: [out] Message buffer. + * + * This function receives a message using a defined communication channel + * between the host and the target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_CHL_MESSAGE_FAILED if receiving of the message failed. + */ +mcd_return_et mcd_receive_msg_f(const mcd_core_st *core, + const mcd_chl_st *channel, uint32_t timeout, + uint32_t *msg_len, uint8_t *msg); + +/** + * mcd_chl_reset_f() - Function resetting a specified communication channel. + * + * @core: [in] : A reference to the targeted system, device or core. Here, + * member instance is allowed to be a null pointer for levels higher + * than core level. + * @channel: [in] : Description of the addressed communication channel. + * + * This function resets a communication channel between the host and the target. + * This allows the communication to be setup again e.g. if the communication + * hangs. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if resetting the communication channel failed. + */ +mcd_return_et mcd_chl_reset_f(const mcd_core_st *core, + const mcd_chl_st *channel); + + +/** + * mcd_chl_close_f() - Function closing a specified communication channel. + * + * @core: [in] : A reference to the targeted system, device or core. + * Here, member instance is allowed to be a null + * pointer for levels higher than core level. + * @channel: [in] : Description of the addressed communication channel. + * + * This function closes a communication channel between the host and the target. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_GENERAL if closing the communication channel failed. + */ +mcd_return_et mcd_chl_close_f(const mcd_core_st *core, + const mcd_chl_st *channel); + + +/** + * DOC: Trace API + * + * Traces allow information to be captured from a running target system or + * platform. A target may contain different trace sources and sinks. A trace + * source is generating trace data (e.g. a core trace or a bus trace unit), + * whereas a trace sink is storing the trace data until it is retrieved via the + * MCD API (e.g. an on-chip or off-chip trace buffer). The MCD API does not + * differentiate between source and sink. Consequently, there needs to be a + * "Trace" for each combination. + */ + + +/** + * mcd_qry_traces_f() - Function querying information about available traces for + * a core. + * + * @core: [in] A reference to the core of which the traces are + * requested. + * @start_index: [in] Start index of the requested traces. This refers to an + * internal list of the target side implementation. + * @num_traces: + * * [in] The number of queried traces starting from the defined + * @start_index. If it is set to '0', no traces are returned but the number of + * all available traces. + * * [out] The number of returned traces. In case the input value of + * @num_traces is '0', this is the number of all available traces for the + * selected core. + * @trace_info: [out] Trace information of the requested traces. This is an + * array allocated by the calling function. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @trace_index is equal or larger than the number of + * traces. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_traces_f(const mcd_core_st *core, uint32_t start_index, + uint32_t *num_traces, + mcd_trace_info_st *trace_info); + + +/** + * mcd_qry_trace_state_f() - Function querying the status of a trace. + * + * @core: [in] A reference to the core to which the trace belongs. + * @trace_id: [in] ID to which this trace refers to. + * @state: [out] The current state of the trace. + * + * This function queries the current status of a particular trace source. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @trace_id is not a valid trace ID. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_qry_trace_state_f(const mcd_core_st *core, uint32_t trace_id, + mcd_trace_state_st *state); + + +/** + * mcd_set_trace_state_f() - Function setting the state and mode of a trace. + * + * This function sets the state and mode of a particular trace source. + * + * @core: [in] A reference to the core to which the trace belongs. + * @trace_id: [in] ID of the trace which is referenced. + * @state: + * * [in] The trace settings to be applied. + * * [out] Returns the current state of the trace. Member @modified is set if a + * member has changed. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @trace_id is not a valid trace ID. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_set_trace_state_f(const mcd_core_st *core, uint32_t trace_id, + mcd_trace_state_st *state); + + +/** + * mcd_read_trace_f () - Function reading trace data from a trace. + * + * @core: [in] A reference to the core to which the trace belongs. + * @trace_id: [in] ID of the trace which is referenced. + * @start_index: [in] Start index of frame to read (0 = oldest frame). This + * refers to an internal list of the target implementation + * which stores the trace frames. + * @num_frames: + * * [in] The number of queried trace frames starting from the defined + * @start_index. If it is set to '0', no trace data is returned but the number + * of all currently available trace frames. + * * [out] The number of read trace frames. In case the input value of + * @num_frames is '0', this is the number of all currently available trace + * frames. + * @trace_data_size: [in] Size of one trace data frame in bytes (for type + * checking). + * @trace_data: [out] Array of trace data structures filled by this + * function. The format depends on the trace source. Standard + * formats are mcd_trace_data_core_st, mcd_trace_data_event_st + * and mcd_trace_data_stat_st. + * + * This function reads trace data from a particular trace source. + * + * Allowed error codes: + * + * - %MCD_ERR_NONE if successful. + * - %MCD_ERR_PARAM if @trace_id is not a valid trace ID, or if start_index is + * larger than the number of available trace frames. + * - %MCD_ERR_GENERAL on any other error. + */ +mcd_return_et mcd_read_trace_f(const mcd_core_st *core, uint32_t trace_id, + uint64_t start_index, uint32_t *num_frames, + uint32_t trace_data_size, void *trace_data); + + +#endif /* MCD_API_H */