opencsd: Custom external decoder C-API (initial development).
Creates C API interface for custom decoders.
Creates C++ wrapper for custom decoder.
Updates registration code to allow registration and deletion of custom
decoders.
Addition of doc file to explain use of custom decoder setAPIDcdFact
Signed-off-by: Mike Leach <mike.leach@linaro.org>
diff --git a/decoder/docs/external_custom.md b/decoder/docs/external_custom.md
new file mode 100644
index 0000000..7efd65d
--- /dev/null
+++ b/decoder/docs/external_custom.md
@@ -0,0 +1,80 @@
+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 builtin 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 provide two 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` : one of these structures exists for each instance of the custom decoder that is created.
+
+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 libary using the supplied name and factory structure.
+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.
+
+
+
+The Decoder Instance Structure
+------------------------------
+
+This structure must be filled in by the `fnCreateCustomDecoder` function implmentation.
+
+There is a single mandatory function in this structure:
+
+ `fnTraceDataIn` : the decoder must provide this as this is called by the library to provide the
+ raw trace data to the decoder.
+
+There are a number of optional callback functions. These allow the custom decoder to call into the library
+and use the same infrastructure as the builting decoders. The callbacks are registed with the custom decoder
+as the libary performs initialisation of connections.
+
+For example, the library will connect the error logging interface to all the decoders. The instance structure
+contains the `fnRegisterErrLogCB` function pointer which will register two error logging callbacks with the custom
+decoder, `fnLogErrorCB` and `fnLogMsgCB`. These can then be called by the custom decoder, and the errors and
+messages will appear in the same place as for the built-in decoders.
+
+Where a custom decoder does not require or support the optional callbacks, then the registration function is set to
+0 in the structure.
+
+
+
+
+
+