diff options
Diffstat (limited to 'decoder/docs/external_custom.md')
| -rw-r--r-- | decoder/docs/external_custom.md | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/decoder/docs/external_custom.md b/decoder/docs/external_custom.md new file mode 100644 index 0000000..64e5191 --- /dev/null +++ b/decoder/docs/external_custom.md @@ -0,0 +1,148 @@ +Attaching External Custom Decoders {#custom_decoders} +================================== + +@brief A description of the C API external decoder interface. + +Introduction +------------ + +An external custom decoder is one which decodes a CoreSight trace byte stream from a source other +than an ARM core which cannot be decoded by the standard built-in decoders within the library. + +An example of this may be a trace stream from a DSP device. + +The external decoder API allows a suitable decoder to be attached to the library and used in the +same way as the built-in decoders. This means that the external decoder can be created and destroyed +using the decode tree API, and will integrate seamlessly with any ARM processor decoders that are part +of the same tree. + +An external decoder will be required to use three standard structures:- + +- `ocsd_extern_dcd_fact_t` : This is a decoder "factory" that allows the creation of the custom decoders. +- `ocsd_extern_dcd_inst_t` : This structure provides decoder data to the library for a single decoder instance. +- `ocsd_extern_dcd_cb_fns` : This structure provides a set of callback functions allowing the decoder to use library functionality in the same way as built-in decoders. + +These structures consist of data and function pointers to allow integration with the library infrastructure. + +Registering A Decoder +--------------------- + +A single API function is provided to allow a decoder to be registered with the library by name. + + ocsd_err_t ocsd_register_custom_decoder(const char *name, ocsd_extern_dcd_fact_t *p_dcd_fact); + +This registers the custom decoder with the library using the supplied name and factory structure. +As part of the registration function the custom decoder will be assigned a protocol ID which may be used in +API functions requiring this parameter. + +Once registered, the standard API functions used with the built-in decoders will work with the custom decoder. + +The Factory Structure +--------------------- +This structure contains the interface that is registered with the library to allow the creation of custom decoder instances. + +The mandatory functions that must be provided include: +- `fnCreateCustomDecoder` : Creates a decoder. This function will fill in a `ocsd_extern_dcd_inst_t` structure for the decoder instance. +- `fnDestroyCustomDecoder` : Destroys the decoder. Takes the `decoder_handle` attribute of the instance structure. +- `fnGetCSIDFromConfig` : Extracts the CoreSight Trace ID from the decoder configuration structure. + May be called before the create function. The CSID is used as part of the creation process to + attach the decoder to the correct trace byte stream. + +`fnPacketToString` : This optional function will provide a human readable string from a protocol specific packet structure. + +`protocol_id` : This is filled in when the decoder type is registered with the library. Used in some API + calls to specify the decoder protocol type. + + + +Creating a Custom Decoder Instance +---------------------------------- + +Once the custom decoder factory has been registered with the library then using the decoder uses the standard creation API:- + +`ocsd_dt_create_decoder(const dcd_tree_handle_t handle, const char *decoder_name, const int create_flags, + const void *decoder_cfg, unsigned char *pCSID)` + + +This creates a decoder by type name in the current decode tree and attaches it to the trace data stream associated with a CoreSight trace ID extracted from +the trace configuration. + +To create a custom decoder instance simply use the custom name and a pointer to the custom configuration structure. + +Calling this on a custom decoder name will result in a call to the factor function `fnCreateCustomDecoder` function:- +`ocsd_err_t CreateCustomDecoder(const int create_flags, const void *decoder_cfg, const ocsd_extern_dcd_cb_fns *p_lib_callbacks, ocsd_extern_dcd_inst_t *p_decoder_inst)` + +This will first require that the `ocsd_extern_dcd_inst_t` structure is populated. + +There is are two mandatory function calls in this structure that may be called by the library + + `fnTraceDataIn` : the decoder must provide this as this is called by the library to provide the + raw trace data to the decoder. + + `fn_update_pkt_mon` : Allows the library to communicate when packet sink / packet monitor interfaces are attached to the decoder and in use. + +The decoder creation process will also fill in the additional information to allow the library to correctly call back into the custom decoder using the `decoder_handle` parameter. + +Secondly the library will provide a structure of callback functions - `ocsd_extern_dcd_cb_fns` - that the decoder can use to access standard library functionality. +This includes the standard error and message logging functions, the memory access and ARM instruction decode functions, plus the current output sink for generic +trace elements generated by the decoder. The decoder is not required to use these functions - indeed the ARM instruction decode will not be useful to none ARM +architecture decoders, but should where possible use these functions if being used as part of a combined ARM / custom decoder tree. This will simplify client +use of the external decoders. + +The `create_flags` parameter will describe the expected operational mode for the decoder. The flags are:- +- `OCSD_CREATE_FLG_PACKET_PROC` : Packet processing only - the decoder will split the incoming stream into protocol trace packets and output these. +- `OCSD_CREATE_FLG_FULL_DECODER` : Full decode - the decoder will split the incoming stream into protocol trace packets and further decode and analyse these to produce generic trace output which may describe the program flow. + +Finally the decoder creation function will interpret the custom configuration (`decoder_cfg`) and fill in the CoreSight Trace ID parameter `pCSID` +for this decoder instance. Decoder configuration structures describe registers and parameters used in programming up the trace source. The only +minimum requirement is that it is possible to extract a CoreSight trace ID from the configuration to allow the library to attach the correct byte +stream to the decoder. + + +Example : The echo_test decoder +-------------------------------- + +The echo_test decoder is provided to both test the C-API interfaces provided for using custom decoders and as a worked example for using these interfaces. + +This decoder is initialised and created by the `c_api_pkt_print_test` program when the `-extern` command line option is used. + +In order to use a custom decoder, the header files for that decoder must be included by the client as they are not part of the built-in provided by the standard library includes. + + #include "ext_dcd_echo_test_fact.h" // provides the ext_echo_get_dcd_fact() fn + #include "ext_dcd_echo_test.h" // provides the echo_dcd_cfg_t config structure. + +The `register_extern_decoder()` function in the test shows how simple the API is to use. + +The implementation of the decoder provides an external function to get a factory structure. + + p_ext_fact = ext_echo_get_dcd_fact(); + +Assuming this returns a structure then the decoder is registered by name. + + if (p_ext_fact) + { + err = ocsd_register_custom_decoder(EXT_DCD_NAME, p_ext_fact); + } + +After this the test uses the same code path as the built in decoders when testing the custom decoder. +The test function `ocsd_err_t create_decoder_extern(dcd_tree_handle_t dcd_tree_h)` is called if the test parameters indicate a custom decoder is needed. +This populates the custom configuration structure specific to the echo_test decoder (`echo_dcd_cfg_t`), then passes this plus the decoder name to the same `create_generic_decoder()` function used when testing the built in decoders. + + + static ocsd_err_t create_decoder_extern(dcd_tree_handle_t dcd_tree_h) + { + echo_dcd_cfg_t trace_cfg_ext; + + /* setup the custom configuration */ + trace_cfg_ext.cs_id = 0x010; + if (test_trc_id_override != 0) + { + trace_cfg_ext.cs_id = (uint32_t)test_trc_id_override; + } + + /* create an external decoder - no context needed as we have a single stream to a single handler. */ + return create_generic_decoder(dcd_tree_h, EXT_DCD_NAME, (void *)&trace_cfg_ext, 0); + } + +From the test program perspective, these are the only changes made to the test program to test this decoder. +The `create_generic_decoder()` then uses the normal C-API calls such as `ocsd_dt_create_decoder()` and `ocsd_dt_attach_packet_callback()` to hook the decoder into the decode tree infrastructure. |