Hi,
While I'm doing some meddlation with the makefiles to build .so libs, it occurs to me that this might be a good time to consider the library names.
Rctdl_c_api and ref_trace_decoder reflect the origins of the code as an ARM project to produce an open source reference trace decode library - prior to this effort being contributed and folded in to OpenCSD.
My thoughts were either libarm_opencsd.so / libarm_opencsd_c_api.so or libarm_cstraced.so / libarm_cstraced_c_api.so
Both of which specify the architecture and function a little better than the old names.
Opinions??
Regards
Mike
(RCTDL appears across much of the source code too, but changing that is a massive job, so I'm not considering that at present).
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
On 3 December 2015 at 15:49, Mike Leach Mike.Leach@arm.com wrote:
My thoughts were either libarm_opencsd.so / libarm_opencsd_c_api.so or libarm_cstraced.so / libarm_cstraced_c_api.so
Both of which specify the architecture and function a little better than the old names.
Opinions??
Why include the ARM in there? The usual convention is a single string, not multiple words - I'd have expected libopencsd.so and libcstraced.so (why are they separate libraries BTW).
(RCTDL appears across much of the source code too, but changing that is a
massive job, so I'm not considering that at present).
coccinelle might be able to help?
Why include the ARM in there? The usual convention is a single string, not multiple words - I'd have expected libopencsd.so and libcstraced.so (why are they separate libraries BTW).
ARM - architecture - as per Intel PT being lib ipt. Not crucial I guess but descriptive. As for the single word convention - see the boost C++ libs! - though in our case multiple words does separate the C-API from the main lib. i.e. libarm_cstraced.so is the C++ lib, libarm_cstrace_c_api.so is the C API wrapper. The windows equivalents would be arm_cstraced.dll and arm_cstrace_c_api.dll, with the static versions libarm_cstraced.lib and libarm_cstraced_c_api.lib. Windows uses arm_cstraced.lib as the link stub for arm_cstraced.dll, so the actual static lib has to have a different name. Again a convention borrowed from the boost libs.
Separate libs as the C API is an optional wrapper on top of the main C++ library. C++ application developers can just use the main lib and get additional flexibility of direct manipulation of the C++ decoder objects should they want that. The C API currently consists of the interface to the DecodeTree object plus a few additions.
coccinelle might be able to help?
Lots of google entries for a hat shop for this! - once I got past that then I spotted what you meant - it is possible I guess - but learning a new tool might take longer than refactoring in a tool I already know. There are actual file names, corresponding #include lines, macro names, variable names, enum prefix names, doxygen comments etc to change, so it is beyond just a few variables and functions to be tweaked.
Regards
Mike
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
-----Original Message----- From: Mark Brown [mailto:broonie@linaro.org] Sent: 03 December 2015 19:16 To: Mike Leach Cc: coresight@lists.linaro.org Subject: Re: Library names.
On 3 December 2015 at 15:49, Mike Leach Mike.Leach@arm.com wrote:
My thoughts were either libarm_opencsd.so / libarm_opencsd_c_api.so or libarm_cstraced.so / libarm_cstraced_c_api.so
Both of which specify the architecture and function a little better than the old names.
Opinions??
Why include the ARM in there? The usual convention is a single string, not multiple words - I'd have expected libopencsd.so and libcstraced.so (why are they separate libraries BTW).
(RCTDL appears across much of the source code too, but changing that is a massive job, so I'm not considering that at present).
coccinelle might be able to help?
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
On 4 December 2015 at 10:18, Mike Leach Mike.Leach@arm.com wrote:
Why include the ARM in there? The usual convention is a single string,
not
multiple words - I'd have expected libopencsd.so and libcstraced.so (why
are
they separate libraries BTW).
ARM - architecture - as per Intel PT being lib ipt. Not crucial I guess but descriptive.
I expect that's deduplicating for a collision on "ipt" which is a very short name. OpenCSD doesn't have that issue.
As for the single word convention - see the boost C++ libs! - though in our case multiple words does separate the C-API from the main lib. i.e. libarm_cstraced.so is the C++ lib, libarm_cstrace_c_api.so is the C API wrapper.
Boost is a bit fun in general though, I'm not sure it's an ideal model.
Separate libs as the C API is an optional wrapper on top of the main C++ library. C++ application developers can just use the main lib and get additional flexibility of direct manipulation of the C++ decoder objects should they want that. The C API currently consists of the interface to the DecodeTree object plus a few additions.
Why would any C++ user care if they pull in a small layer of wrapper code? If things were the other way around and there were a C++ wrapper around a C library there would be an advantage in keeping the C library out of the C++ ABI dependency chain but that doesn't apply here since the C library is going to pull in the C++ dependencies anyway.
Why would any C++ user care if they pull in a small layer of wrapper code? If things were the other way around and there were a C++ wrapper around a C library there would be an advantage in keeping the C library out of the C++ ABI dependency chain but that doesn't apply here since the C library is going to pull in the C++ dependencies anyway.
I'm currently looking at issues regarding windows DLLs vs Linux .so. In a linux shared object, everything is exported by default - so all is well, in windows DLLs nothing is exported by default, so we need to explicitly export stuff hence lots of interesting code such as this from rctdl_c_api.h (the main C-API include file )
/* ensure C bindings */
#ifdef WIN32 /* windows bindings */ #ifdef _RCTDL_C_API_DLL_EXPORT #ifdef __cplusplus #define RCTDL_C_API extern "C" __declspec(dllexport) #else #define RCTDL_C_API __declspec(dllexport) #endif #else #ifdef __cplusplus #define RCTDL_C_API extern "C" __declspec(dllimport) #else #define RCTDL_C_API __declspec(dllimport) #endif #endif #else /* linux bindings */ #ifdef __cplusplus #define RCTDL_C_API extern "C" #else #define RCTDL_C_API #endif #endif
So the windows C-API DLL explicitly exports all the C-API functions - handy for those requiring a nice C interface - especially when binding to scripting languages such as python etc. So on the windows side, this DLL is required if we are to achieve a scriptable interface - which was one of our (ARMs) goals. The windows C API DLL currently statically links the C++ lib.
The equivalent code in the C++ library would be quite extensive - all the classes need to be exported - so at present I have not done that. I am not 100% sure when this will be done. Thus on windows the C++ and C-API are managed as separate projects - so too in linux for consistency. I also like the separation - two header files / two libraries (albeit with a dependency chain in linux) - the user chooses to use one or the other of the interfaces, but not both.
So the current goal of all this is to get .so working in linux to ensure that the library access is acceptable to the perf development - and other linux devs who prefer C interfaces, and decide on the final windows strategy later.
Regards
Mike
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
-----Original Message----- From: Mark Brown [mailto:broonie@linaro.org] Sent: 04 December 2015 10:46 To: Mike Leach Cc: coresight@lists.linaro.org Subject: Re: Library names.
On 4 December 2015 at 10:18, Mike Leach Mike.Leach@arm.com wrote:
Why include the ARM in there? The usual convention is a single
string, not
multiple words - I'd have expected libopencsd.so and libcstraced.so
(why are
they separate libraries BTW).
ARM - architecture - as per Intel PT being lib ipt. Not crucial I guess but descriptive.
I expect that's deduplicating for a collision on "ipt" which is a very short name. OpenCSD doesn't have that issue.
As for the single word convention - see the boost C++ libs! - though in our case multiple words does separate the C-API from the main lib. i.e. libarm_cstraced.so is the C++ lib, libarm_cstrace_c_api.so is the C API wrapper.
Boost is a bit fun in general though, I'm not sure it's an ideal model.
Separate libs as the C API is an optional wrapper on top of the main C++ library. C++ application developers can just use the main lib and get additional flexibility of direct manipulation of the C++ decoder objects should they want that. The C API currently consists of the interface to the DecodeTree object plus a few additions.
Why would any C++ user care if they pull in a small layer of wrapper code? If things were the other way around and there were a C++ wrapper around a C library there would be an advantage in keeping the C library out of the C++ ABI dependency chain but that doesn't apply here since the C library is going to pull in the C++ dependencies anyway.
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
I think is this mostly a question for Mike, but I'll send it more broadly.
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
--- Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com
Hi Tor,
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
You are right, there isn't, it needs adding (to the C++ side too).
RCTDL_C_API rctdl_err_t rctdl_dt_remove_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space);
Would remove the accessor matching on address and memory space (accessors are not allowed to overlap so this should suffice).
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Yes - a function such as:-
RCTDL_C_API rctdl_err_t rctdl_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space, const uint32_t mem_length, const PMEMACCFN pFn);
with
PMEMACCFN defined as something like:-
typedef rctdl_err_t (* PMEMACCFN) ( const rctdl_vaddr_t address, const rctdl_mem_space_acc_t mem_space, uint32_t *num_bytes, uint8_t *p_buffer); would be sufficient?
Again would need adding to C++ side.
The memory accessor interface is quite immature at the moment. The only examples we are currently using are snapshots and thus fixed - no need to remove memory areas, and everything is files or buffers.
Regards
Mike
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
-----Original Message----- From: CoreSight [mailto:coresight-bounces@lists.linaro.org] On Behalf Of Jeremiassen, Tor Sent: 08 December 2015 16:19 To: coresight@lists.linaro.org Subject: Trace Decoder Memory Accessor
I think is this mostly a question for Mike, but I'll send it more broadly.
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com _______________________________________________ CoreSight mailing list CoreSight@lists.linaro.org https://lists.linaro.org/mailman/listinfo/coresight
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
Mike,
Looks good.
Tor
--- Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com
-----Original Message----- From: Mike Leach [mailto:Mike.Leach@arm.com] Sent: Tuesday, December 08, 2015 10:46 AM To: Jeremiassen, Tor; coresight@lists.linaro.org Subject: RE: Trace Decoder Memory Accessor
Hi Tor,
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
You are right, there isn't, it needs adding (to the C++ side too).
RCTDL_C_API rctdl_err_t rctdl_dt_remove_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space);
Would remove the accessor matching on address and memory space (accessors are not allowed to overlap so this should suffice).
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Yes - a function such as:-
RCTDL_C_API rctdl_err_t rctdl_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space, const uint32_t mem_length, const PMEMACCFN pFn);
with
PMEMACCFN defined as something like:-
typedef rctdl_err_t (* PMEMACCFN) ( const rctdl_vaddr_t address, const rctdl_mem_space_acc_t mem_space, uint32_t *num_bytes, uint8_t *p_buffer); would be sufficient?
Again would need adding to C++ side.
The memory accessor interface is quite immature at the moment. The only examples we are currently using are snapshots and thus fixed - no need to remove memory areas, and everything is files or buffers.
Regards
Mike
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
-----Original Message----- From: CoreSight [mailto:coresight-bounces@lists.linaro.org] On Behalf Of Jeremiassen, Tor Sent: 08 December 2015 16:19 To: coresight@lists.linaro.org Subject: Trace Decoder Memory Accessor
I think is this mostly a question for Mike, but I'll send it more broadly.
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com _______________________________________________ CoreSight mailing list CoreSight@lists.linaro.org https://lists.linaro.org/mailman/listinfo/coresight
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
Hi Tor,
New definitions in rctdl_c_api.h.
/*! * Add a memory access callback function. The decoder will call the function for opcode addresses in the * address range supplied for the memory spaces covered. * * @param handle : Handle to decode tree. * @param st_address : Start address of memory area covered by the callback. * @param en_address : End address of the memory area covered by the callback. (inclusive) * @param mem_space : Memory space(s) covered by the callback. * @param p_cb_func : Callback function * * @return RCTDL_C_API rctdl_err_t : Library error code - RCDTL_OK if successful. */ RCTDL_C_API rctdl_err_t rctdl_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t st_address, const rctdl_vaddr_t en_address, const rctdl_mem_space_acc_t mem_space, Fn_MemAcc_CB p_cb_func);
/*! * Remove a memory accessor by address and memory space. * * @param handle : Handle to decode tree. * @param st_address : Start address of memory accessor. * @param mem_space : Memory space(s) covered by the accessor. * * @return RCTDL_C_API rctdl_err_t : Library error code - RCDTL_OK if successful. */ RCTDL_C_API rctdl_err_t rctdl_dt_remove_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t st_address, const rctdl_mem_space_acc_t mem_space);
Also in rctdl_if_types.h the definition of the callback fn. (here as it can be used in the C++ API as well. C++ API can also use a class interface).
/** * Callback function definition for callback memory accessor type. * * When using callback memory accessor, the decoder will call this function to obtain the * memory at teh address for the current opcodes. The memory space will represent the current * exception level and security context of the traced code. * * Return the number of bytes read, which can be less than the amount requested if this would take the * access address outside the range of addresses defined when this callback was registered with the decoder. * * Return 0 bytes if start address out of covered range, or memory space is not one of those defined as supported * when the callback was registered. * * @param address : start address of memory to be accessed * @param mem_space : memory space of accessed memory (current EL & security state) * @param reqBytes : number of bytes required * @param *byteBuffer : buffer for data. * * @return typedef uint32_t : Number of bytes actually read, or 0 for access error. */ typedef uint32_t (* Fn_MemAcc_CB)(const rctdl_vaddr_t address, const rctdl_mem_space_acc_t mem_space, const uint32_t reqBytes, uint8_t *byteBuffer);
These functions are now demonstrated and tested in simple_pkt_print_c_api when run with -decode -test_cb.
Regards
Mike
---------------------------------------------------------------- Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE ----------------------------------------------------------------
-----Original Message----- From: Jeremiassen, Tor [mailto:tor@ti.com] Sent: 08 December 2015 16:49 To: Mike Leach; coresight@lists.linaro.org Subject: RE: Trace Decoder Memory Accessor
Mike,
Looks good.
Tor
Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com
-----Original Message----- From: Mike Leach [mailto:Mike.Leach@arm.com] Sent: Tuesday, December 08, 2015 10:46 AM To: Jeremiassen, Tor; coresight@lists.linaro.org Subject: RE: Trace Decoder Memory Accessor
Hi Tor,
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
You are right, there isn't, it needs adding (to the C++ side too).
RCTDL_C_API rctdl_err_t rctdl_dt_remove_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space);
Would remove the accessor matching on address and memory space (accessors are not allowed to overlap so this should suffice).
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Yes - a function such as:-
RCTDL_C_API rctdl_err_t rctdl_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const rctdl_vaddr_t start_address, const rctdl_mem_space_acc_t mem_space, const uint32_t mem_length, const PMEMACCFN pFn);
with
PMEMACCFN defined as something like:-
typedef rctdl_err_t (* PMEMACCFN) ( const rctdl_vaddr_t address, const rctdl_mem_space_acc_t mem_space, uint32_t *num_bytes, uint8_t *p_buffer); would be sufficient?
Again would need adding to C++ side.
The memory accessor interface is quite immature at the moment. The only examples we are currently using are snapshots and thus fixed - no need to remove memory areas, and everything is files or buffers.
Regards
Mike
Mike Leach +44 (0)1254 893911 (Direct) Principal Engineer +44 (0)1254 893900 (Main) Arm Blackburn Design Centre +44 (0)1254 893901 (Fax) Belthorn House Walker Rd mailto:mike.leach@arm.com Guide Blackburn BB1 2QE
-----Original Message----- From: CoreSight [mailto:coresight-bounces@lists.linaro.org] On Behalf Of Jeremiassen, Tor Sent: 08 December 2015 16:19 To: coresight@lists.linaro.org Subject: Trace Decoder Memory Accessor
I think is this mostly a question for Mike, but I'll send it more broadly.
Looking at the C API it looks like the two alternatives for providing access to the image of the code that was traced is either through in-memory buffers or as binary files. I currently don't see a way to remove the accessors should the memory locations be "invalidated".
Would it be possible to add the ability to remove accessors and also to add a third type of accessor, a pointer to a function that will access the requisite locations when called?
Tor Jeremiassen, Ph.D. Senior Member Technical Staff SDO Foundational Tools Texas Instruments Ph: 832 939 2356 13905 University Lane Fax: 832 939 2015 Sugar Land, TX 77479 Email: tor@ti.com _______________________________________________ CoreSight mailing list CoreSight@lists.linaro.org https://lists.linaro.org/mailman/listinfo/coresight
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
-
Jeremiassen, Tor -
Mark Brown -
Mike Leach