Home

UM1112 User manual - FTP Directory Listing

1. UM1112 MME API MME_SendCommand Send a command to a specific transformer Definition include lt mme h gt MME ERROR MME SendCommand MME TransformerHandle t Handle MME Command_t CmdInfo_p Arguments Handle Handle of the targeted transformer CmdiInfo_p Pointer to an allocated structure that contains the parameters of the command Returns MME SUCCESS The command has been successfully inserted in the command queue waiting to be processed by MME MME DRIVER_NOT_INITIALIZED The MME driver has not been initialized MME NOMEM The memory required to complete this command is not available MME INVALID HANDLE The handle does not refer to an existing transformer MME INVALID ARGUMENT CmdInfo_pis invalid Description Send a command and its associated parameters to a specific transformer The command s parameters are passed using the structure MME_Command_t This in turn uses a number of sub structures to describe specific parameters When inserted the MME_CommandState_t of the command is set to MME COMMAND PENDING Comments Call type non blocking function call See also MME_AbortCommand 3 MME_WaitCommand MME_Command _t 8182595 Rev 5 73 224 MME API UM1112 MME_Term Definition Arguments Returns Description Comments See also 74 224 include lt mme h gt MME_ERROR MME_Term void None MME_ SUCCESS MME _DRIVER_NOT INITIALIZED MME HANDLES STILL OPEN
2. 11 33 Reset address 200 00000 204 TESLE oor dsadredadeidta ieina 202 204 209 Running test suites auaa aaaea aaa 13 ky 8182595 Rev 5 223 224 UM1112 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY W
3. 8182595 Rev 5 65 224 MME API UM1112 66 224 Table 7 Tuneable values for MME parameters continued Value Description MME TUNEABLE EXECUTION LOOP HIGHEST Tune the priority of each of the execution PRIORITY loop threads The execution loops are MME TUNEAB NORNAL PRI LE EXECUTION ORITY LOOP_ABOVE_ MME TUNEAB PRIORITY LE_EXECUTION _ LOOP_NORNAL_ MME TUNEAB NORNAL PRI ORITY LE_EXECUTION _ LOOP_BELOW_ MME TUNEAB PRIORITY LE_EXECUTION _ LOOP_LOWEST_ responsible for performing transform requests and altering global parameters No execution loop should have a higher priority than the manager or transformer threads The priorities of the execution loops should be such that MME TUNEABLE EXECUTION LOOP_ HIGHEST PRIORITY has the highest priority and MME TUNEABLE EXECUTION LOOP_ LOWEST PRIORITY has the lowest 1 Value interpreted as an OS priority level Unlike most MME calls it is possible to modify tuneables before the MME API has been initialized Note Most tuneables do not affect behavior once MME has been initialized and hence they should modified before calling MME Init 8182595 Rev 5 3 UM1112 MME API MME_NotifyHost Notify host that transformer has generated an event Definition include lt mme h gt MME ERROR MME NotifyHost MME Event _t event MME Command _t commandiInfo MME ERROR errorCode Ar
4. define MME TYPE MPGV_ forward vertical IE 1 ES E MPGV Picture _t U32 U32 U32 U32 U32 U32 typedef MME GenericParams_t MPGV_DecodeParams_t MME_LENGTH MPGV Parameters to be used by a MPEG transformer to be decode an MPEG picture MPGV_picture_type MPGV_full_pel_forward_vector MPGV_forward_f_code MPGV_full_pel_backward_vector MPGV_backward_f_code MPGV_forward_horizontal MPGV_forward_vertical Type of the picture that has to be decoded As described in ISO IEC 13818 2 As described in ISO IEC 13818 2 As described in ISO IEC 13818 2 As described in ISO IEC 13818 2 As described in ISO IEC 13818 2 As described in ISO IEC 13818 2 The following code provides an example MME _ Command t command MME CommandStatus_t status MME DataBuffer t buffers 4 MPGV_DecodeParams_t params command StructSize sizeof command command CmdEnd MME COMMAND END RETURN NOTIFY 8182595 Rev 5 3 UM1112 MME supplement See also 3 command DueTime now 20 MS command CmdStatus_p amp status command NumInputBuffers 3 command NumOutputBuffers 1 command Buffers p amp buffers command Param_p amp params status StructSize sizeof status Setup the input buffers compressed data backward reference picture and forward reference picture Setup the output buffer the decompressed picture Setup the transformer specific parameter structure MME
5. 115 152 MME secre ceran irea sere ees 15 ICS_channel_free 115 153 Compilation 22200 eae 11 ICS_channel_open 115 116 154 COMES Ge foie ica Hyak ws aad aaa 20 a an Se aoe eee 203 ICS_channel_recv be et ete ican anne a doe 1 15 155 ICS_channel_release 115 156 D ICS_channel_send 115 116 157 ICS_channel_unblock 115 158 Data structure ICS_cpu_connect 123 159 MME eT 45 ICS_cpu_disconnect FO arr we ere a 123 160 Debug ICS cpu_info se cece cece es 114 161 assertions 0 00 0 c eee eee 216 ICS_cpu_init re ee re ee 4 14 162 SUPPOrt ee eee 12 ics cpu_init 0 0e cece cece ee eeee 126 Deferred commands ics_cpu_lookup 113 128 ky 8182595 Rev 5 221 224 Index UM1112 icS Cou_mask 00000s 113 129 L eps no eT EES ft TEE cota 11 ics_cpu_self L u annann T M sasestenmeeaberatans AAO TAAA ics cpu_start 00008 113 133 ICS _cpu_term 0005 114 163 M ics_cpu_type ss sees E o EE ET 201 203 ics_cpu_type 21 sees eee eee T SINCE Gan eiermcesaaiinsnian sna 203 207 ics_cpu_version 113 135 MME oe hs LLL coors 15 49 ics_debug_chan 124 136 See also Transformer ICS_debug_dump 5 124 164 Buffer and cache 020005 23 ics_debug flags
6. UM1112 Inter core system ICS API ICS_port_lookup Lookup an ICS port handle Definition include lt ics h gt ICS_ERROR ICS port_lookup const ICS CHAR portName ICS UINT flags ICS LONG timeout ICS PORT portp Arguments portName Port name string flags Various flag bits which affect behavior timeout Time in milliseconds to block waiting for a response portp Port handle pointer used to return discovered handle Returns ICS SUCCESS Successfully discovered port handle portp Discovered port handle Errors ICS NOT INITIALISED ICS not initialized ICS NAME NOT FOUND Port name was not found in the name server ICS INVALID ARGUMENT An invalid argument was supplied ICS ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Context Callable from task context only Description ICS port lookup attempts to discover the port named portName in the global 3 name server If found then ICS_SUCCESS is returned and the associated port handle is returned If multiple port handles with the same name are present in the global name server then the handles are returned in a round robin order portName should be an ASCII NUL 0 terminated string of length not exceeding ICS PORT MAX NAME characters not including the NUL flags can be set to ICS BLOCK to cause the function to block until the named port is registered in the name s
7. struct bsp_reg_mask bsp_sys_boot_enable STI7141_SYSCONF_SYS_CFG08 1 1 eSTB STI7141_ SYSCONF SYS CFGO8 2 2 eCM STI7141_SYSCONF_ SYS CFG26 1 1 audio s1 TI7141 SYSCONF SYS CFG28 1 1 video struct bsp reg mask bsp sys_reset_registers STI7141_SYSCONF SYS CFGO8 1 lt lt 6 1 lt lt 6 eSTB STI7141_ SYSCONF SYS CFGO8 1 lt lt 7 1 lt lt 7 eCM STI7141 SYSCONF SYS CFG27 1 1 audio s1 TI7141 SYSCONF SYS CFG29 1 1 video CPU core name Filename stx7141 st40 estb name c include lt bsp _bsp h gt const char bsp_cpu_ name estb Filename stx7141 st231 audio name c include lt bsp _bsp h gt const char bsp cpu_name audio 8182595 Rev 5 3 UM1112 MME supplement Appendix B MME supplement This appendix provides supplementary information to Chapter 2 Using the MME API B 1 Parameter encoding This section describes a simply interface for a simple MPEG video decoder showing how the configuration parameters can be customized for each transformer B 1 1 Samples definitions lists the MPEG video decoders specific definitions Table 32 MPEG video decoders specific definitions Type Description Defines the different picture types an MPEG video MPGV PictureType t i ype_ transformation can handle Parameters to be used for the next transformation Poy GlObalEdrams
8. ICS_channel_open Open a send channel for communication Definition Arguments Returns Errors Context Description 154 224 include lt ics h gt ICS_ERROR ICS channel open ICS CHANNEL channel ICS_UINT flags ICS CHANNEL SEND schannelp channel Channel handle flags Various flag bits which affect behavior schannelp Send channel handle pointer ICS SUCCESS Successfully opened the send channel schannelp Contains allocated send channel handle ICS _NOT_INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid channel handle was supplied ICS NOT CONNECTED Target CPU is not connected ICS ENOMEM Failed memory resource allocation ICS SYSTEM _ERROR A system error occurred Callable from task context only In order to send data using a CPU channel it must first be opened by calling ICS channel _open This will allocate an associated send channel handle which is returned in schannelp The channel handle parameter can either be one allocated locally with ICS channel _alloc or one supplied from a different CPU by looking it up for example in the name server or being supplied the opaque channel handle through another mechanism It is an error to attempt to open multiple send channels to a given channel channel should be a valid channel handle as allocated by ICS channel _alloc either on the the local CPU or on a remote one Curr
9. Note 2 3 2 2 3 3 Note 3 It is essential that all host and companion processors in a system are initialized However some stages of the initialization may be omitted for particular operating environments supported by MME e For multi processor OS21 systems all steps are required for companion processors Registering transformers is optional for host processors e For Linux kernel space operation MME is initialized automatically when the MME module is loaded Registering local transformers is optional Section 2 11 2 Linux on page 32 contains further details about loading Linux kernel modules It is not possible to register transformers in Linux user space Initializing MME The MME library is initialized using the following function MME ERROR MME Init void The MME library must be loaded and initialized on each processor and user space process in the system The Linux kernel MME implementation automatically calls MME_Init during module load No other API can be called until the library is initialized In a system where multiple threads use MME it is permissible for each thread to call MME Init The first call performs initialization returning MME SUCCESS if no error occurs Any subsequent calls simply return MME_ALREADY INITIALIZED Thatis a second call to MME Init does not re initialize MME Calls to MME_Init are not counted Thus particular care must be taken de initializing MME when sharing the MME between
10. UM1112 Using the MME API Note 2 4 1 2 5 Note ky It is not possible to terminate a transformer if there are any outstanding commands pending If this is attempted an error is returned Querying the capabilities of a transformer It is sometimes useful to examine the capabilities of a transformer before it is instantiated either for error checking or to ensure the correct transformer is being used MME allows transformers to publish their capabilities without requiring a handle This enables transformers to be examined before any calls to MME_InitTransformer The following function is used for this purpose MME ERROR MME GetTransformerCapability const char transformerName MME TransformerCapability t transformerCapability The transformer is able to describe its preferred input and output formats together with its version number Transformer specific details can also be copied into a user supplied buffer Buffer and cache management Data buffers are used throughout MME to transport unstructured data between the application and transformers In this case unstructured is used to mean that data has identical representation on all processors regardless of endianness or similar concerns it is a simple stream of bytes A data buffer describes a logical group of memory locations that contain or are intended to contain media data A data buffer is represented by the structure MME DataBuffer t Each data buffer is co
11. 202 224 External BSP location The Multicom 4 library can also be built using the external BSP source directory specified by the BSP_SRCDIR make environment variable This directory should have exactly the same directory hierarchy and file locations as the one in the Multicom 4 source tree The included files makebspst40 inc and makebspst231 inc can then be modified to specify the new SoC BSPs The BSP_INCDIR environment variable can also be used to supply an external include directory during compilation of the external BSP Under the Linux kernel the original Multicom 4 source srce ics Makefile directory still needs to be modified to specify the new SoC All the BSP files can be located in the external BSP directory The BSP_SRCDIR and BSP_INCDIR paths supplied during the building of the ICS Linux kernel module must be relative to the Multicom 4 source tree source src ics directory BSP data structures This section describes each of the BSP data structures for CPU mailbox reset and boot addresses The data structures for the reset and boot addresses are defined for each CPU It is important therefore that the order of the entries defined for the table of CPUs described in Section A 2 1 are synchronized with the order of entries for the reset and boot address structures defined in reset c and listed in Section A 2 3 CPU table This data structure defines an entry in the CPU name table The CPU table is used to map CPU core
12. Description Return a pointer to the ICS version string 3 This string takes the form major number minor number patch number text That is a major minor and release number separated by decimal points and optionally followed by a colon and a text string 8182595 Rev 5 135 224 Inter core system ICS API UM1112 ics_debug_chan Set the debug logging output channel Definition Arguments Returns Errors Context Description Note 136 224 include lt ics h gt void ics debug chan ICS UINT flags flags Bitmask of debug channel flags None None Callable from task and interrupt context Can be called before ICcS_cpu_init ics debug _chan sets the debug output channel of the ICS system The ICS debug libraries are built with conditional debugging enabled for each subsystem Each subsystem logs debug and error messages depending on the flags set by ics debug _flags The output channel for these debug message is controlled by calling this function The set of valid debug channel flag bits are detailed in Table 25 These are encoded as bitmask values and hence combinations such as ICS DBG STDOUT ICS DBG LOG are permitted Table 25 ICS debug channel flags Channel flag Description ICS _DBG STDOUT Log all messages to console STDOUT ICS DBG STDERR Log all message to console STDERR ICS _DBG LOG Log all messages to cyclic buffer The ICS library is built with the de
13. define MME TYPE ThisIsAGlobalName U32 This parameter can be extracted as follows MME PARAM params ThisIsAGlobalName 0xAC3 printf d n MME PARAM params ThisIsAGlobalName See also MME_INDEXED_PARAM MME_PARAM_SUBLIST MME_LENGTH 68 224 8182595 Rev 5 kyy UM1112 MME API MME_PARAM_SUBLIST Extract named parameter sub array Definition include lt mme h gt define MME PARAM SUBLIST params name Arguments params Pointer to a parameter array of type MME GenericParams t name Name of the parameter to be extracted from the array Returns A pointer to a sub list of parameters has type MME_GenericParams t Description Extract a named parameter sub array from a parameter array This macro uses other special purpose macros or named constants to process the name For example the following macros define a parameter name called ThisIsASublist enum MME OFFSET ThisTsASublist 2 This parameter can be extracted as follows sublist MME PARAM SUBLIST params ThisIsASublist MME PARAM sublist SomeParameter OxAC3 Returns A pointer to a sub list of parameters has type MME_GenericParams t See also MME_PARAM 3 MME_INDEXED_PARAM MME_LENGTH 8182595 Rev 5 69 224 MME API UM1112 MME_PingTransformer Definition Arguments Returns Description Comments See also 70 224 include lt mme h gt Check that a transformer is still responding MME ERROR MME PingTransfor
14. mflags will be set according to the message data buffer memory attributes Valid flags are ICS_INLINE ICS_CACHED ICS_UNCACHED and ICS_PHYSICAL srcCpu Will be set to the ICS logical CPU number of the sending CPU payload will contain the inline data if ICS_INLINE is set in mflags 8182595 Rev 5 171 224 Inter core system ICS API UM1112 ICS_msg_post Definition Arguments Returns Errors Context Description 172 224 include lt ics h gt Post an asynchronous receive on a port typedef struct ics_msg desc ICS_OFFSET data ICS SIZE size ICS MEM FLAGS mflags ICS _UINT srcCpu ICS CHAR payload ICS MSG INLINE DATA ICS_MSG_ DESC ICS ERROR ICS msg post ICS MSG DESC rdesc ICS MSG EVENT eventp port rdesc eventp ICS SUCCESS eventp ICS NOT INITIALISED ICS INVALID ARGUMENT ICS HANDLE INVALID ICS PORT CLOSED ICS ENOMEM ICS SYSTEM ERROR Callable from task context only ICS PORT port Port handle Receive descriptor pointer Pointer to an ICS_MSG_EVENT handle Successfully posted a receive The associated message event handle on success ICS not initialized An invalid argument was supplied An invalid port handle was supplied Port has been closed Failed memory resource allocation A system error occurred ICS_msg_post posts an asynchronous nonblocking receive to the supplied port handle to match new message arrivals Me
15. w amp Transformer_name_3 Companion acting as host _ gt Companion ST231 l l a l Transformer_name_6 J 8182595 Rev 5 17 224 Using the MME API UM1112 2 1 3 Note Note 18 224 Commands and events Transformer instances are controlled by sending them commands Each command is a self contained unit of work consisting of a due time a command code some transformer specific parametric information and the data buffers to be transformed by the command All commands of the same priority are executed in due time order The priority of a command is inherited from the transformer instance with which it is associated The priority of a transformer instance is supplied by the application when the transformer is instantiated Because commands are executed on different processors and potentially can be deferred for execution by different hardware accelerators this does not imply that across the system as a whole all commands will be issued or complete in due time order Each command is associated with a status structure that among other things provides the unique identifier by which the command can be managed together with an indication of the command s current state Commands are submitted for execution asynchronously that is the function to issue the command completes successfully before the command has complete
16. A transformer is considered frame based if its entire input and output buffers can be determined at the point the transform MME_TRANSFORM command is issued Any transformer that does not require the use of MME_SEND_ BUFFERS can therefore be considered to be frame based A transformer is considered streaming if both its input and output buffers require the use of MME SEND BUFFERS Pure streaming transformers while perfectly legitimate are quite rare Much more common are hybrid transformers consisting of frame based input buffers and streaming output buffers or vice versa Frame based operation Frame based operation is considered to be the default within MME Although other modes of operation are possible if ever there is a choice between frame based or streaming operation then the frame based approach is recommended By adopting frame based operation the amount of interrupt activity on both CPUs can be minimized Particularly for media processors this maximizes processing bandwidth Because all buffers are available before the transformation begins there is no risk of the transformer blocking which has the potential to seriously degrade performance Frame based operation is a particularly good approach for decoding multiplexed audio video streams common in embedded multimedia processing For both audio and video decode the size of the output frame or picture is known in advance of processing It is also fairly easy to identify complet
17. Wz z max page size 1 Detailed information on relocatable libraries can be found in the S740 Micro toolset user manual 7379953 and in the ST200 Micro toolset user manual 8063762 Relocatable library tool The ST40 and ST200 toolsets contain a tool for managing relocatable libraries The tool is called sh4rltool in the ST40 toolset and st200rItool in the ST200 toolset When the name of one or more relocatable libraries is given on the command line the tool lists the undefined global symbols in the libraries These symbols may need to be imported into the main program that uses the libraries The tool also generates a linker script fragment for importing or exporting the symbols This feature is useful when the executable requires more than one relocatable library each with its own non overlapping API requirements For more information concerning the relocatable library tool issue one of the following commands sh4rltool help st200rltool help Debugging support Comprehensive debug tracing is included in the Multicom 4 code but by default these messages are not compiled into the libraries In order to be able to use the debug logging the library code will need to be rebuilt using the following make command line or environment option For ICS debugging export DEBUG _CFLAGS DICS DEBUG For MME debugging export DEBUG _CFLAGS DMME_ DEBUG Debug libraries can be built alongside the default non debug libraries
18. include lt mme h gt MME ERROR MME RegisterTransformer const char name MME AbortCommand_t abortFunc MME GetTransformerCapability t getTransformerCapabilityFunc MME InitTransformer_t initTransformerFunc MME ProcessCommand_t processCommandFunc MME TermTransformer_t termTransformerFunc name A unique name for the transformer abort The transformer function to call when an abort request is made getTransformerCapabilityFunc The transformer function to call when a capability request is made initTransformerFunc The transformer function to call when a transformer is initialized processCommandFunc The function to call when a command is sent to the transformer termTransformerFunc The function to call when a transformer instance is terminated MME SUCCESS The device has been successfully initialized Registers a transformer for later instantiation on the CPU from which this call is made The name argument must not be longer than MME_MAX TRANSFORMER_NAME bytes The error code MME INVALID ARGUMENT will be returned if the name is too long The name of the transformer implicitly describes the type of that transformer for example com st dvd acc Ac3DecoderMacro This can be confirmed by using MME GetTransformerCapability to examine the capability of transformer if required Call type blocking function call MME_InitTransformer MME_DeregisterTransformer MME_IsTransformerRegistered 3 8182595 Rev 5
19. make f Makefile st40 make f Makefile st200 To build the kernel module for Linux requires a command sequence of the form export KERNELDIR lt path_to_original_ linux _kernel_sources gt export O lt path_ to built linux kernel sources gt For example to build the kernel module for Linux for the MB671 STi7200 issue the following commands adjusting the kernel paths as necessary for the desired target kernel export KERNELDIR usr src linux sh4 2 6 23 17_stm23 0122 export O lib modules linux sh4 2 6 23 17_stm23_0122 mb671 cd source make ARCH sh CROSS COMPILE sh4 1linux For example to build the kernel module for Linux for the B2000 STiH415 issue the following commands adjusting the kernel paths as necessary for the desired target kernel export KERNELDIR usr src linux arm b2000 2 6 32 y export O lib modules linux arm b2000 2 6 32 y cd source make ARCH arm CROSS_COMPILE armv7 1linux where ARCH and CROSS COMPILE are Linux environment variables On ARM based Linux builds if the kernel does not export the symbol set_iounmap_nonlazy its reference from Multicom can be disabled using the following Make command line or environment option export MULTICOM EXTRA CFLAGS DDISABLE ITOUNMAP_NONLAZY 8182595 Rev 5 9 224 Building Multicom UM1112 1 3 Note 10 224 To build the Linux userspace MME interface library issue the following commands cd source make ARCH sh CROSS COMPILE sh4 linux f Make
20. wa UM1112 yf i life augmented User manual Multicom 4 Overview This document describes Multicom 4 which provides an inter processor communication system for ST40 and ST200 processors on STMicroelectonics SoCs Multicom combines the multi media engine API MME and the inter core system ICS MME provides an API for controlling media transformers for example an MPEG2 decoder which resides on either the local processor or a remote processor ICS is a run time system that provides program execution management and communications between all the CPUs on an ST SoC ICS replaces the EMBX layer in previous versions of Multicom with a simpler approach to communication and with the addition of facilities for loading starting monitoring and recovering from errors in other CPUs in the SoC Figure 1 Multicom 4 overview Host processor Optional Companion processors Application Drivers Video Audio driver driver ee l l y Multicom 4 Inter processor communication ICS 7 ee CS oee a a Transformer Transformer Transformer Transformer a Extended mailbox communications system EMBX a low level communications API used to manage communication between CPUs implemented in the Multicom 3 x product November 2013 8182595 Rev 5 1 224 www st com Contents UM1112 Contents Preface otis be 55
21. Cached buffers that are not aligned to the largest cache line size in the system pose significant problems because this makes writes by the companion CPU to those addresses unsafe 8182595 Rev 5 ky UM1112 Using the MME API 2 5 3 3 Subdividing a data buffer The application may divide the scatter pages returned by MME_AllocDataBuffer into application oriented scatter pages so long as the divided pages reside entirely within the allocated pages An application must not make assumptions about the number of scatter pages returned by MME_AllocDataBuffer unless the flag MME_ALLOCATION_PHYSICAL is specified in which case a single page is returned A simplified example of dividing a physical scatter page is shown below This example takes the scatter page returned by MME_AllocDataBuffer and divides it into NUM_SCATTER_PAGES scatter pages MME DataBuffer t dataBuffer MME ScatterPage t origPage MME ScatterPage_t scatterPage NUM_SCATTER_ PAGES int newPageSize unsigned char pageBase Allocate a buffer of size bytes MME AllocDataBuffer hdl size MME ALLOCATION PHYSICAL amp dataBuffer Keep a record of the original scatter page array origPage amp dataBuffer gt ScatterPages p Calculate size of each new scatter page ignore the remainder bytes newPageSize origPage gt Size NUM_SCATTER_PAGES pageBase origPage gt Page p Set the data buffer to use the new array of sc
22. ICS_region_phys2virt Translate a physical memory region into a local Definition Arguments Returns Errors Context Description 192 224 virtual address include lt ics h gt ICS_ERROR ICS region _phys2virt ICS OFFSET paddr ICS SIZE size ICS MEM FLAGS mflags ICS VOID addressp paddrp Physical address to be translated size Size of memory region mflags Memory attribute flags requested addressp Returned virtual address pointer ICS SUCCESS Successfully translated address addressp Virtual address translation ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID No translation found Callable from task and interrupt context ICS region phys2virt translates a physical address into a local CPU virtual address It does this by making use of the region tables as created with ICS _region_add If a matching region is found then the corresponding virtual address mapping will be returned in addressp For a matching region to be found the local region table must contain a region which covers the whole of the supplied memory region and that also has the same memory attributes as specified in the mflags argument If no matching region is found then ICS INVALID ARGUMENT is returned paddr should be a valid physical address size should be the size of the region being translated mflags should be a valid memory attribute flag such as I
23. Lsource lib os21 st231 lmme lics Lsource lib os21 st231 stx7200 audio0 lics_bsp rmain Wl wrap _write_r To compile a Linux userspace ST40 MME test program issue a command similar to the following sh4 linux gcc o test out test c Isource include Lsource lib linux st40 lmme The ST231 fno dismissible load option is only necessary if the companion code has not correctly enabled SCU speculation for all possible memory locations that will be accessed by the ST200 The linker wrap _write_r argument allows the ICS system to intercept all text output from the target executable and log it into the CPU cyclic log buffers for each CPU Building relocatable libraries for use with Multicom 4 ICS includes infrastructure that allows relocatable libraries to be dynamically loaded into the running CPUs OS21 only See the Chapter 5 Overview of the inter core system ICS on page 110 for more details In order to compile and link a compatible ELF module use the fpic and the rlib options as in the following examples For ST40 sh4gcc o dyn rl fpic mruntime os21 Isource include rlib dyn c For ST200 st200cc mcore st231 mruntime o0s21 dyn c o dyn out Isource include fpic rlib fvisibility protected For the ST200 Micro Toolset R6 3 0 in order to overcome a bug detected only in that toolset add the following option to the command line 8182595 Rev 5 11 224 Building Multicom UM1112 1 5 1 1 6 12 224
24. MME SIZE Size MME MemoryHandle t Handle_p Handle Handle of the transformer to associate with this memory registration Base Virtual address of the base of the memory region being registered Size Size in bytes of the memory region being registered Handle_p Pointer to an MME_MemoryHandle_t that will contain the handle of the registered memory region MME SUCCESS The memory region was successfully registered MME DRIVER_NOT_ INITIALIZED The MME driver has not been initialized MME INVALID HANDLE The handle does not refer to an existing transformer MME INVALID ARGUMENT One or more of the supplied arguments are invalid MME ICS ERROR An ICS subsystem error occurred Register a memory region with a specific transformer This must be done for all memory regions that are used as data buffers to MME_SendCommand If cached and uncached translation of the physical memory region are to be used then the region must be registered with both its cached and uncached virtual addresses Base and Size are automatically aligned and rounded to the associated system page size Call type blocking function call MME_DeregisterMemory a This does not apply to data buffers allocated using MME_AllocDataBuffer ky 8182595 Rev 5 71 224 MME API UM1112 MME_RegisterTransformer Register a transformer for instantiation on a CPU Definition Arguments Returns Description Comments See also 72 224
25. Pipelined FirstHalfInSoftware ctx cmd if ctx gt lastCmd There is a deferred command wait for it to complete err2 is the MME ERROR code to set in the command s status err2 Pipelined WaitForPreviousSecondHalf ctx ctx gt lastCmd MME NotifyHost MME COMMAND COMPLETED EVT ctx gt lastCmd err2 if MME TRANSFORM DEFERRED errl The first part is in a deferred state remember this ctx gt lastCmd cmd this function returns MME TRANSFORM DEFERRED if successful errl Pipelined SetupSecondHalf ctx cmd else ctx gt lastCmd NULL return errl1 Pipelined transformers block execution for the previous stages of the pipeline to complete If the software side is running ahead of the hardware side then the transform function blocks and at this point execution of all commands on the current processor of the same priority halt In the above example Pipelined WaitForPreviousSecondHal1f blocks using an operating system primitive until the hardware side has completed Poorly tuned pipelined transformers can be harmful to processor bandwidth Pipelined transformers are therefore best implemented only for single purpose companion processors Note Pipelined _WaitForPreviousSecondHalf must not busy wait as this will disrupt processing at lower priorities 3 4 3 Streaming and hybrid transformers Streaming and hybrid transformers are required to support the MME_ SEND BUFFERS comma
26. The transformer handle is invalid Flags or DataBuffer_p is invalid This command allocates memory that can be optimally communicated to the transformer indicated by Handle Flags can be used to specify additional useful properties required of the allocated memory For example its cache ability or whether it is required to be contiguous Call type blocking function call MME_FreeDataBuffer 8182595 Rev 5 3 UM1112 MME API MME_DebugFlags Set MME debug logging flags Definition include lt mme h gt MME_ERROR MME DebugFlags MME_DBG FLAGS Flags Arguments Flags Bitmask of debugging flags See MME_DBG_FLAGS on page 91 Returns MME SUCCESS The debug flags were successfully set MME DRIVER_NOT_INITIALIZED The MME driver has not been initialized MME ICS ERROR An ICS subsystem error occurred Description Sets the MME debugging flags to the supplied bitmask value ky 8182595 Rev 5 53 224 MME API UM1112 MME_DeregisterMemory Deregister memory region Definition include lt mme h gt MME ERROR MME DeregisterMemory MME MemoryHandle t Handle Arguments Handle Handle of the memory region registered with MME RegisterMemory Returns MME SUCCESS The memory region was successfully deregistered MME DRIVER_NOT INITIALIZED The MME driver has not been initialized MME INVALID HANDLE The handle does not refer to an existing memory region registration MME ICS ERROR An ICS subsystem error occurred De
27. WE own SET2 8182595 Rev 5 207 224 ICS board support package UM1112 208 224 flags 0 base void MBOX1_ADDR Audio LX Mailbox MBOX1 1 interrupt 0 Audio owns SET1 flags 0 base void MBOX1 ADDR 0x100 Audio LX Mailbox MBOX1 2 interrupt AUDIO MBOX IRQ WE own SET2 flags 0 base void MBOX3 ADDR ST40 ESTB Mailbox MBOX3 1 interrupt ESTB MBOX IRQ WE own SET1 flags 0 base void MBOX3 ADDR 0x100 ST40 ESTB Mailbox MBOX3 2 interrupt 0 ECM owns SET2 flags 0 unsigned int bsp_mailbox_count sizeof bsp mailboxes sizeof bsp mailboxes 0 Filename stx7141 st231 audio mbox c include lt bsp _bsp h gt define MBOXO ADDR Oxfe211000 define MBOX1 ADDR Oxfe212000 define MBOX2 ADDR Oxfe211800 define MBOX3 ADDR O0xfe212800 include lt os21 st200 sti7141 h gt struct bsp_mbox_regs bsp_mailboxes base void MBOXO ADDR Video LX Mailbox MBOX0O 1 interrupt 0 flags 0 base void MBOXO ADDR 0x100 Video LX Mailbox MBOX0 2 3 8182595 Rev 5 UM1112 ICS board support package interrupt 0 flags 0 base void MBOX2 ADDR ST40 ECM Mailbox MBOX2 1 interrupt 0 flags 0 base void MBOX2 ADDR 0x100 ST40 ECM Mailbox MBOX2 2 interrupt 0 flags 0 base void MBOX1_ADDR Audio LX Ma
28. assumption regarding whether it is held in a particular processor s cache in order to guarantee correctness In many cases the application is in a position to provide hints that can reduce this pessimistic behavior These hints have no effect if memory is uncached and can therefore be applied by an application even for affinity allocated memory see Section 2 5 1 Allocating data buffers on page 24 For example a buffer populated by an incoherent DMA peripheral and not subsequently read by the CPU is known not to be in a processor s cache It is therefore wasteful to spend time flushing such a buffer from memory For this reason each MME scatter page can be marked with the cache management hints shown in Table 2 on page 26 prior to being made available to the host Table 2 MME_ScatterPage_t FlagsIn and FlagsOut Flag Flagsin FlagsOut 2 Description For a host this means that all input buffers are coherent with memory and the output buffers are not present in the cache For a companion this means that no buffers are present in the cache This directs MME to avoid any unnecessary cache invalidations or cache flushes wo wo MME DATA CACHE COHERENT Data is reused by the companion without being read by another MME DATA TRANSIENT 3 processor or hardware accelerator This directs MME not to flush the companion s data cache 1 The FlagsIn field is set by the host application before the comman
29. e Managing transformer lifetimes see Section 2 4 on page 22 Transformer instances can be created or destroyed using the MME API It is also possible to examine the capabilities of a transformer before it is instantiated e Buffer and cache management see Section 2 5 on page 23 Data buffers are used extensively by MME to transport unstructured data between the application and the transformers MME provides API calls to allocate and manage data buffers as well as subdividing them Flags are provided to influence cache management of data buffers e Application and transformer specific data see Section 2 6 on page 27 MME provides a mechanism for passing application specific or transformer data to and from the transformer e Issuing commands see Section 2 7 on page 27 The central function of the MME API is to perform transformations Three types of commands may be sent to a transformer as described in Section 2 8 on page 29 Section 2 10 on page 31 describes the difference between a frame based transformer and a stream based transformer The chapter finishes with a description of linking and loading issues for different operating systems Section 2 11 on page 32 Initialization Initialization of a system is divided into two stages 1 Initializing MME which presupposes that the ICS is initialized 2 Registering transformers if they are being used 3 8182595 Rev 5 UM1112 Using the MME API Note 2 3 1 Note
30. entryAddrp Arguments fname Local OS filename of ELF file flags Various flag bits which affect behavior entryAddrp Returns loaded object ELF start entry address Returns ICS SUCCESS Successfully loaded the ELF image entryAddrp ELF start entry address Errors ICS NAME NOT FOUND Filename was not found ICS INVALID ARGUMENT An invalid argument or ELF image was supplied ICS ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred Context Callable from task context only Can be called before ICS_cpu_init Description ics load_elf_file is used to load an ELF file image on the master CPU and 3 unpack it so that it can be executed on the Slave Companion CPUs On successful completion the ELF start entry address is returned to the caller in the entryAddrp argument fname should be a local OS filename from where the ELF image can be obtained Currently no flags bits are defined and this parameter must be set to zero entryAddrp should be a valid pointer to an ICS_OFFSET sized object 8182595 Rev 5 147 224 Inter core system ICS API UM1112 ics_load_elf_image Unpack an ELF memory image Definition Arguments Returns Errors Context Description 148 224 include lt ics h gt ICS_ ERROR ics _load_elf image ICS CHAR image ICS_UINT flags ICS OFFSET entryAddrp image Virtual memory address of ELF file image flags Various flag bits which affect behavior e
31. include lt ics h gt ICS _ ERROR ICS nsrv_add const ICS CHAR name ICS VOID data ICS SIZE size ICS_UINT flags ICS_NSRV_HANDLE handlep name Object name to be added data Object data to be associated with the name size Size of object data flags Various flag bits which affect behavior handlep Pointer to an ICS_NSRV_HANDLE handle ICS SUCCESS Successfully registered named object ICS NOT INITIALISED ICS not initialized ICS NAME IN _USE name is aready in use ICS INVALID ARGUMENT An invalid argument was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Callable from task context only ICS nsrv_add adds the supplied object data to the global name server associating it with the supplied name string Duplicate names are allowed and in this case the nameserver returns matching object lookups in a round robin order name should be an ASCII 0 terminated string of length not exceeding ICS NSRV_MAX NAME characters not including the 0 data should be a pointer to the object data to be associated with the name string in the name server size should be the size in bytes of the object data It must not exceed ICS NSRV_MAX DATA in size Currently no flags bits are defined and this parameter must be set to zero handlep should be a non NULL pointer to an ICS_NSRV_HANDLE sized object in which the a
32. the application should call ICS_cpu_disconnect to free up any resources associated with that CPU connection The application should then proceed to re load and restart the program running on that CPU either using the ICS ics_cpu_ functions or other libraries available for this purpose Once 8182595 Rev 5 123 224 Overview of the inter core system ICS UM1112 5 9 124 224 the CPU has been restarted the application should call ICS_cpu_connect to re establish communications with the re started CPU Then the watchdog for that CPU should be re primed using ICS_ watchdog reprime Debug logging support ICS provides a debugging facility where all text output from the running CPU cores is logged to a cyclic buffer Functions are provided to dump out these logs on a per CPU basis hence allowing diagnosis of issues when a multi core debugger session is not possible Table 21 Function name Description ics debug flags Set the debug logging flags ics debug chan Set the debug logging output channel Ics debug dump Dump out the debug log ics debug flags andics debug_chan are used to set up the debugging system prior to ICS_cpu_init being called ics debug _flags defines the subsystems of ICS for which debug logging is required ics debug chan determines whether debugging is logged to stdout stderr or to a cyclic buffer in memory ICS_debug_dump is called while ICS is running and dumps out all the messages logged t
33. 122 ICS provides a dynamic module loading system based on the relocatable loader library provided with the ST40 and ST200 Micro Toolsets using OS21 This API allows code modules to be loaded and unloaded into any of the running CPUs on demand e CPU watchdog support see Section 5 8 on page 123 In order to facilitate fault detection and recovery ICS provides a CPU watchdog API that allows callback functions to be registered These callback functions are then triggered whenever one of the monitored CPUs fails to update a internal counter within a fixed time period e Debug logging support see Section 5 9 on page 124 ICS provides a debugging facility where text output from the running CPU cores is logged to a cyclic buffer APIs are provided to dump out these logs on a per CPU basis 5 2 ICS initialization and system loading 3 There are three stages to ICS initialization and system loading these are described in the following sections Section 5 2 1 ICS configuration and setup Section 5 2 2 CPU loading and initialization Section 5 2 3 ICS initialization and termination on page 114 8182595 Rev 5 111 224 Overview of the inter core system ICS UM1112 5 2 1 5 2 2 Note Note 112 224 ICS configuration and setup The ICS BSP is used for configuring and setting up ICS for a specific SoC as described in Appendix A ICS board support package on page 207 The ICS system library is linked into the initial application bin
34. 2 1 4 Callbacks bcc cceaucdeer dt wot beddap ee phareiadeee ered oad 18 2 1 5 DUG TIME sess cece et hte ba a ia rE ak ele aa ete BU eae 18 2 1 6 Transformer priorities 0000 cece eee 19 2 1 7 SUUGIUTE SIZE sic eaten ge ka ce aE ee els ehh a Sea a ee as 20 2 2 Summary of MME facilities nnau 20 2 3 INA ZAUON n4 hae be aaa be eRe a E E bd eve bv bade 20 2 3 1 Initializing MME 0 220 ee 21 2 3 2 Registering transformers 0 0c e eee eee 21 2 224 8182595 Rev 5 ky UM1112 Contents 2 3 3 Examples saare e hoe ae Raw on in ee Pe A es 21 2 4 Managing transformer lifetimes 0 0 eee 22 2 4 1 Querying the capabilities of a transformer 005 23 2 5 Buffer and cache management aausaauaa aeaea 23 2 5 1 Allocating data buffers 0 0 aaua aaau 24 2 5 2 Manually managing data buffers aaua aaaea 24 2 5 3 Subdividing a data buffer 20 0 0 eee ee 25 2 5 4 Data buffers in Linux user mode 0 000 eee 26 2 5 5 Cache management 2 000 cece eae 26 2 6 Application and transformer specific data 00 00 e eee 27 2 7 ISSUING commandS 4 eG aed ws Bie Mae we a ee Re ae eh Warm 27 2 7 1 Aborting commands 0 000 eee 29 2 8 Fault detection and recovery 0 cece eee eee 29 2 9 Types of commands o cico ta dacev ds ne hew gna wl hemody gat ecetue eo 30 2 9 1 Transforming data 00 tee 3
35. 24 Table 23 Example STi7200 MB519 BSP Registry Logical CPU CPU name CPU type 0 st40 st4o 1 videoo st231 2 audioo st231 3 video st231 4 audio st231 Table 24 Example STi7141 MB628 BSP Registry Logical CPU CPU name CPU type 0 estb st4o 1 ecm st4o 2 video st231 3 audio st231 ics_cpu_name ics_cpu_type 8182595 Rev 5 3 UM1112 Inter core system ICS API ics_cpu_mask Query the logical CPU bitmask Definition include lt ics h gt ICS _ULONG ics cpu_mask void Arguments None Returns A logical ICS CPU bitmask Errors None Context Callable from task and interrupt context Can be called before IcS_cpu_init Description Returns the logical CPU bitmask of the running system Each set bit n representing that logical CPU number n is present This information is determined by querying the BSP Registry of the running system Normally this bitmask will be fulling populated that is for an N CPU system all bit positions from 0 to N 1 will be set However for debugging purposes it may be partially populated See also ics_cpu_lookup for details of the ICS logical CPU numbering system 3 8182595 Rev 5 129 224 Inter core system ICS API UM1112 ics_cpu_name Query the BSP Registry for CPU name Definition Arguments Returns Errors Context Description See also 130 224 in
36. MME_COMMAND_STILL_EXECUTING Terminate a connection with a MME Free all the associated memory space Call type blocking function call MME Init 8182595 Rev 5 Terminate a connection with MME The operation complete correctly The MME driver has not been initialized Could not terminate not all transformers have been terminated Could not terminate due to locally registered transformer instantiations still being active 3 UM1112 MME API MME_TermTransformer Terminate a transformer instance Definition include lt mme h gt MME ERROR MME TermTransformer MME TransformerHandle t handle Arguments handle Handle of the transformer to terminate Returns MME SUCCESS The operation complete correctly MME DRIVER NOT INITIALIZED MME has not been initialized MME INVALID HANDLE Invalid transformer handle MME COMMAND STILL EXECUTING A command is still executing Description Terminate a transformer instance and free all the associated resources A transformer can not be terminated while a command is executing Comments Call type blocking function call See also MME_InitTransformer 3 MME_AbortCommand 8182595 Rev 5 75 224 MME API UM1112 MME_WaitCommand Definition Arguments Returns Description 76 224 include lt mme h gt MME ERROR MME WaitCommand MME CommandId_t CmdId MME Event_t Event_p MME Time_t Timeout Handle CmdiId Event_p Timeout MME SUCCESS MME DRI
37. O lib modules linux sh4 2 6 23 17_stm23_0122 mb671 cd test make ARCH sh CROSS _COMPILE sh4 1linux To build the kernel test modules for Linux for the B2000 STiH415 issue the following commands adjusting the kernel paths as necessary for the desired target kernel export KERNELDIR usr src linux arm b2000 2 6 32 y export O lib modules linux arm b2000 2 6 32 y cd test make ARCH arm CROSS _COMPILE armv7 linux where ARCH and CROSS COMPILE are Linux environment variables To build the userspace test MME executables for Linux issue the following commands cd test make ARCH sh CROSS COMPILE sh4 linux f Makefile linux make ARCH arm CROSS COMPILE armv7 linux f Makefile linux 8182595 Rev 5 ky UM1112 Building Multicom 1 4 Note 1 5 Note 3 Compiling and linking against the Multicom 4 libraries In order to compile a test application using the Multicom 4 libraries you need to link the application against the binary library For example to compile an OS21 ST40 test program for the MB671 STi7200 issue a command similar to the following sh4gcc mboard mb671 mruntime os21 o test40 out test c Isource include Lsource lib os21 st40 lmme lics Lsource lib os21 st40 stx7200 st40 lics_bsp rmain Wl wrap write_r For the AudioO ST231 CPU the command is st200cc mboard mb671_audio0 msoc sti7200 mcore st231 mruntime 0s21 o test200 out test c fno dismissible load Isource include
38. PARAM params MPGV_ picture type pt MME PARAM params MPGV_ full pel forward vector 0 a E 7 7 7 err MME SendCommand handle MME TRANSFORM amp command MPGV_GlobalParams_t MME_AllocationFlags_t MME_SendCommand MME_PARAM 8182595 Rev 5 215 224 Advanced build options UM1112 Appendix C Advanced build options Note C 1 Note 216 224 This appendix describes how environment or make command line variables can be used to tailor the Multicom build process See Chapter 1 Building Multicom on page 8 for details on how to build the software Many of the options described below alter they way the software is built For such changes it is important that the tree is cleaned before building to prevent make s build avoidance techniques from interfering with the changes Debugging assertions and logging All target resident source code is supplied with the Multicom distribution this allows application developers to enable the in built assertion checking and or run time logging to help them identify problems Debug assertions are runtime tests compiled into the application that to a limited extent verify correct operation of the program This is supplementary to normal debugging which requires only debugging information Compiling with debugging information is discussed in Chapter 1 Building Multicom on page 8 All these facilities are controlled at build time by a single environment or make variable DEB
39. This is the port callback function that is invoked for each message that arrives at the port It will be called using the same param argument as supplied during ICS port_alloc The rdesc pointer will refer to a completed ICS_MSG_ DESC descriptor Normally the callback function should process this incoming rdesc and return ICS_ SUCCESS which will cause the message to be consumed If however it cannot be consumed at this point in time then ICS FULL should be returned which will cause the message to be held on the per port message queues It can then be later retrieved by calling IcS_ msg _recv or ICS_msg_post In order to preserve message ordering once the callback function has returned ICS FULL no further callbacks will be generated on that port Callbacks will only be enabled once the associated port message queue has been emptied 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_port_cpu Return logical CPU number associated with port Definition include lt ics h gt ICS EXPORT ICS ERROR ICS port cpu ICS PORT port ICS UNIT cpuNump Arguments port The associated port handle cpuNump Return logical CPU number Returns ICS SUCCESS Successfully determined port logical CPU number Errors ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid port handle was supplied Context Called from task and interrupt context Description ICS
40. VOID address ICS_OFFSET paddrp ICS MEM FLAGS mflagsp address Virtual memory address paddrp Physical address pointer to be returned mflagsp Memory attribute flags to be returned ICS SUCCESS Successfully translated address paddrp Physical address translation mflagsp Memory attribute flags of translated address ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID No translation found ICS SYSTEM ERROR A system error occurred Callable from task and interrupt context ICS region virt2phys translates a local CPU virtual address into a physical one It does this by making use of the region tables as created with ICS _region_add If a matching region is found then the corresponding physical address and memory attributes will be written to paddrp and mflagsp respectively If no matching region is found then the call will fall back to the OS specific virtual to physical mapping system and in this case mflagsp will be set to ICS PHYSICAL address should be a local CPU virtual address paddrp should be a valid pointer to an ICS_ OFFSET object mflagsp should be a valid pointer to an ICS_MEM_ FLAGS object 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_watchdog_add Definition Arguments Returns Errors Context Description 3 include lt ics h gt Install a CPU watchdog handler typedef void ICS WATCH
41. a CPU crashes and is rebooted multiple watchdog callbacks are not generated However the callback handler may still be called if other CPUs in the monitored cpuMask bitmask fail callback must be a non NULL ICS WATCHDOG CALLBACK function pointer param is an optional parameter pointer to be supplied to the callback function It may be NULL 8182595 Rev 5 195 224 Inter core system ICS API UM1112 cpuMask is a bitmask of each logical CPU to be monitored by this watchdog callback Currently no flag bits are defined and this parameter must be set to zero handlep should be a valid pointer to an ICS_ WATCHDOG object 3 196 224 8182595 Rev 5 UM1112 Inter core system ICS API ICS_WATCHDOG_CALLBACK Watchdog callback function Definition include lt ics h gt typedef void ICS WATCHDOG CALLBACK ICS WATCHDOG handle ICS_ VOID param ICS UINT cpuNum Arguments handle Watchdog handle associated with this callback param param argument as supplied with the install function cpuNum Logical CPU number of failed CPU Returns None Errors None Context Called from task context only Description This is the watchdog callback function that is invoked for each watchdog trigger that occurs for the monitored CPUs It will be called using the same param argument as supplied during ICS_watchdog_add It is also supplied with the allocated watchdog handle and the failed cpuNum Note As this callback is called from
42. aborted This is achieved using the following function MME ERROR MME AbortCommand MME CommandId_t CmdId This function is asynchronous it returns successfully before the request for abortion has been passed on An abort is effectively a request for a command to immediately enter the MME COMMAND FAILED state As such the application will be notified if an abort was possible by the command entering this state The application will receive a callback assuming these are requested If the command could not be aborted it will complete as normal entering either the MME_COMMAND COMPLETED state or the MME_ COMMAND FAILED state with a different error code Although a command in the MME_COMMAND_ PENDING state can always be aborted it is not always possible for commands in the MME_COMMAND EXECUTING or deferred states to be aborted as support for abort from these states is transformer specific Since commands can asynchronously move from state to state it is possible fora command to change state between the application observing that command in the MME COMMAND PENDING state and issuing the abort As such the application should always consult the state of the aborted command before assuming success Fault detection and recovery MME and the underlying ICS system provide simple facilities to aid the device driver writer in coping with unexpected failures of the companion CPUs In particular CPU crashes are detected and any outstanding comma
43. an ICS heap these calls are useful for presenting to the ICS region management code Doing this allows local heaps to be mapped into the remote CPUs so that it can be used for zero copy message passing and buffer sharing heap should be a valid heap handle as allocated with ICS_heap_create See also ics heap base 3 ics_heap_size 8182595 Rev 5 145 224 Inter core system ICS API UM1112 ics_heap_size Query ICS heap for size Definition Arguments heap Returns Errors Context Description See also 146 224 include lt ics h gt ICS SIZE ics heap size ICS HEAP heap Heap handle Associated heap parameter 0 Size of heap not found Callable from task context only Can be called before ICS_cpu_init ics heap size returns the full size of the supplied ICS heap This is one of three functions that allow the caller to query the base and size of an ICS heap these calls are useful for presenting to the ICS region management code Doing this allows local heaps to be mapped into the remote CPUs so that it can be used for zero copy message passing and buffer sharing heap should be a valid heap handle as allocated with ICS_heap_create ics _heap_base ics_heap_pbase 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_load_elf_file Load and unpack an ELF file Definition include lt ics h gt ICS ERROR ics load_elf file const ICS CHAR fname ICS_UINT flags ICS LOAD
44. base address of the supplied ICS heap This is one of three functions that allow the caller to query the base and size of an ICS heap these calls are useful for presenting to the ICS region management code Doing this allows local heaps to be mapped into the remote CPUs so that it can be used for zero copy message passing and buffer sharing heap should be a valid heap handle as allocated with ICS_heap_create Valid mElags values are ICS_CACHED and ICS_UNCACHED See also ics heap _pbase 3 ics_heap_size 8182595 Rev 5 141 224 Inter core system ICS API UM1112 ics_heap_create Create an ICS heap Definition Arguments Returns Errors Context Description 142 224 include lt ics h gt ICS_ERROR ics _heap_create ICS VOID heapBase ICS SIZE heapSize ICS_UINT flags ICS HEAP heapp heapBase Optional base address of heap heapSize Size in bytes of heap being created flags Various flag bits which affect behavior heapp Heap handle pointer used to return allocated handle ICS SUCCESS CPU start was issued successfully heapp Allocated heap handle ICS INVALID ARGUMENT An invalid argument was supplied ICS ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred Callable from task context only Can be called before ICS_cpu_init ics heap create creates a heap from a contiguous physical memory region This heap can then be used to allocate and free buffers h
45. be set to either ICS_TRUE or ICS_ FALSE on completion ICS_msg_wait 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_msg_wait Block an asynchronous message receive event for completion Definition include lt ics h gt ICS ERROR ICS msg wait ICS MSG EVENT event ICS _ LONG timeout Arguments event Message event handle timeout Time in milliseconds to block waiting for the event Returns ICS SUCCESS Call completed successfully readyp Boolean of event completion state Errors ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid event handle was supplied ICS PORT _CLOSED Port has been closed ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Wait timed out Context Callable from task context only Description ICS_msg_wait blocks on the supplied message event handle until the associated event completes or the timeout period expires In all cases the message event is released on completion of this call event should be a valid message event handle as returned by ICS _msg_ post timeout is the amount of time in milliseconds to block waiting for a message event to complete See also ICS_msg_test 3 8182595 Rev 5 179 224 Inter core system ICS API UM1112 ICS_nsrv_add Add a named object with the name server Definition Arguments Returns Errors Context Description 180 224
46. by adding the following option to the make command line MULTILIB dbg This causes the debug enabled libraries to be placed in a separate dbg subdirectory in the build tree In order to link the test executables against these libraries add the same MULTILIB make command line option when compiling the tests As soon as the debug enabled libraries have been built debug logging can be configured dynamically by using the ics debug flags and MME DebugFlags API calls The debug logging level can also be configured statically by specifying the following make command line or environment option For ICS debugging export DEBUG _CFLAGS DICS DEBUG DICS DEBUG FLAGS 1 For MME debugging export DEBUG _CFLAGS DMME DEBUG DMME DEBUG FLAGS 1 Where ICS _DEBUG_FLAGS and MME DEBUG FLAGS can be set to a bitmask for each subsystem for which logging is required See Section 5 9 Debug logging support on page 124 for further details 8182595 Rev 5 ky UM1112 Building Multicom 1 6 1 Note 1 7 Note 1 8 3 For the Linux kernel modules the ICS and MME debugging level can be set by using the ics_debug_flags and MME DebugFlags function calls or by setting the module parameters see Section C 1 Debugging assertions and logging on page 216 Debug logging By default all ICS and MME debug log messages are logged to a cyclic buffer Under Linux these logs can be easily accessed using the procfs filing system For
47. example to dump out the current log for CPU 1 issue the command cat proc ics cpu01 log This command dumps out all the messages logged since the last time the log was dumped If the logging output has exceeded the size of the cyclic buffer then only the newer messages are seen By linking against debug built libraries the size of the cyclic log buffer is greatly increased Running the tests under OS21 Running the OS21 based tests is just a matter of loading and running the primary test executable For tests that make use of multiple CPUs the corresponding executables are loaded directly by the test harness All test executables are compiled into the test bin directory and should be executed from the top level test directory For example running a test on an MB671 may use a command such as cd test sh4xrun t stmc mb671 st40 tapmux_mux 1 e bin os21 st40 mb671 st40 ics channel channel00 main elf The elf files are simply stripped versions of the out files to reduce load times Running the tests under Linux To run the test modules under Linux first the appropriate Linux kernel needs to be booted After booting log into the target CPU as a root user and load the Multicom and test modules Load the Multicom modules using cd source insmod src ics ics ko init 0 debug _flags 0 insmod src ics ics_user ko insmod src mme mme ko init 0 debug _flags 0 insmod src mme mme_user ko 8182595 Rev 5 13 224 Building Multicom
48. for loading an initial ELF file into a CPU and starting it The dynamic code loading functions assume that the ICS code is already running in the CPUs and are intended to add and start a new load module on the companion CPU at run time They are intended for applications where the code running in the companions is to be determined at run time or to be modified and augmented as the application runs The intention is that load modules can be used to modularize the software running on the ICS companion CPUs avoiding large statically linked firmware binaries having to be built for each CPU Load modules are expected to be relocatable ELF library files which can either be located in memory or loaded from a filing system These functions are built on the r1_1ib library as provided with the ST40 and ST200 Micro Toolsets using OS21 See the user manuals for these toolsets in particular to understand how the hierarchy of load modules is defined Table 19 Dynamic code loading functions Function name Description ICS _dyn_load_ file Load a dynamic ELF module from a local file ICS _dyn_load_image Load a dynamic ELF module from a memory image Ics _dyn_unload Unload a previously loaded dynamic ELF module ICS dyn_load_file and ICS _dyn_load_image load a dynamic ELF module from a local file or from a memory image respectively for a specified target CPU They load and relocate the code for the target CPU dynamically linking it against the
49. its context structure and supply a pointer to this global variable The initialization function for single instance transformers should return MME_NOMEM if the application attempts multiple instantiation Any transformer that is not forced to operate as single instance through hardware dependency should be implemented as a multiple instance transformer In fact extensive use of global variables should be avoided even for hardware transformers that are currently single instance because this may limit their utility in future SoC devices that may contain multiple instances of that hardware Termination MME _TermTransformer_t is called as a result of an application call to MME TermTransformer see Section 2 4 Managing transformer lifetimes on page 22 MME TermTransformer_t takes the context parameter described in Section 3 2 to specify the transformer instance that should be terminated MME TermTransformer_t reverses all the steps performed during initialization It releases any hardware resources it is using and frees any memory Querying the capabilities of a transformer The transformer must implement a function that permits the application to query whether a transformer meets its requirements see Section 2 4 1 Querying the capabilities of a transformer on page 23 This function must be compatible with the function pointer type MME _GetTransformerCapability_t which is an argument of MME RegisterTransformer typedef MME ERROR M
50. location This should then be processed by the caller before being later released with ICS_channel_release No protocol is used within the channel communication system so it is the responsibility of the programmer to determine how much data is contained within each supplied FIFO entry but obviously it cannot exceed the FIFO slot size that was used to create the channel 8182595 Rev 5 155 224 Inter core system ICS API UM1112 ICS_channel_release Release an ICS channel FIFO buffer Definition Arguments Returns Errors Context Description 156 224 include lt ics h gt ICS ERROR ICS channel release ICS CHANNEL channel ICS VOID buffer channel Channel handle buf Buffer pointer ICS SUCCESS Successfully released a buffer ICS_NOT_INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid channel handle was supplied ICS SYSTEM ERROR A system error occurred Callable from task and interrupt context ICS channel release releases a channel buffer back to the FIFO It should be called immediately after the caller has processed the FIFO data in order to maintain the in order nature of FIFO processing channel should be a valid channel handle buffer should be the last channel buffer address supplied by ICS channel recv or the callback handler 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_channe
51. make the best possible attempt to decode the data and use the transformer specific status parameters to indicate to the application that the output may be incorrect 3 8182595 Rev 5 UM1112 Writing an MME transformer For correctly formed commands the exact action required by the transformer depends upon the command code supplied by the application For this reason typical implementations of this command simply examine the command code and call a helper function For example MME ERROR EXMPL ProcessCommand void ctx MME Command_t cmd switch cmd gt CmdCode case MME TRANSFORM return EXMPL Transform ctx cmd case MME SEND BUFFERS return EXMPL SendBuffers ctx cmd case MME SET GLOBAL TRANSFORM PARAMS return EXMPL SetParameters ctx cmd J return MME INVALID ARGUMENT Note Frame based transformers do not usually support the MME_SEND BUFFERS command so that value is often omitted from the switch statement The MME_TRANSFORM command instructs the transformer to perform a data transformation either on buffers supplied with the command or for streaming transformers on buffers sent using the MME_SEND BUFFERS command The MME_TRANSFORM command should not complete until at least a single frame of data has been processed Note If the transformer has the concept of frames and follows the streaming model then the transformer must be provided with a parameter identifying how many bytes of data should be processed be
52. multiple threads Registering transformers A transformer is registered with a name and associated function pointers by using the following function MME ERROR MME RegisterTransformer const char name MME AbortCommand_t abortFunc MME GetTransformerCapability_t getTransformerCapabilityFunc MME InitTransformer_t initTransformerFunc MME _ProcessCommand_t processCommandFunc MME _TermTransformer_t termTransformerFunc Each of the functions pointed to is described in detail in Chapter 3 Writing an MME transformer Example This section provides examples of how MME is started on a host CPU and on a companion CPU The examples illustrate the startup sequence for the host application and for the companion It is assumed that the operating system has been started on each CPU For brevity return code checks have been omitted from the examples 8182595 Rev 5 21 224 Using the MME API UM1112 2 4 22 224 Host side example Initialize ICS err ICS _cpu_init 0 j Intitialize the MME system for a host res MME Init Init transformer res MME InitTransformer com st mcdt mme test_transformer amp initParams amp transformerHand1le Send a transform command res MME SendCommand transformerHandle MME TRANSFORM j res MME TermTransformer transformerHandle Companion side example Initialize ICS err ICS _cpu_init 0 Intitialize the MME system for a compa
53. names onto their logical CPU numbers struct bsp cpu_info char name char type int num unsigned int flags Table 28 CPU name table structure Structure member name Description name CPU core name for example estb or audio type CPU architecture for example st40 or st231 num Logical CPU number for this core ve to disable flags Various flag bits The order of the CPU definitions in this table must match that used in the CPU boot and reset tables in reset c 8182595 Rev 5 ky UM1112 ICS board support package A 2 2 Note A 2 3 3 The BSP declaration of this table are normally found in the top level cores c file so that they are shared across all the CPU cores The following declarations need to be made in the BSP normally found in cores c extern unsigned int bsp_cpu_count extern struct bsp_cpu_info bsp_cpus Where bsp_cpus is the array of CPU definitions and bsp_cpu_count is set to the number of entries in that array Mailbox table This structure defines an individual Mailbox entry Each mailbox entry defines a set of 4 x 32 bit mailbox registers For local mailboxes an interrupt request number or address on OS21 should be provided so that interrupts can be accepted on that set of mailboxes For non local mailboxes that is mailboxes owned by other CPUs then this should be set to 0 Each Mailbox IP on the SoC actually provides two independe
54. only documented in the Release notes included ARM examples in Section 1 2 Building the library code on page 9 and Section 1 3 Building the test code on page 10 and made minor corrections Section 1 5 Building relocatable libraries for use with Multicom 4 on page 11 Section 1 6 Debugging support on page 12 and Section 2 11 3 Relocatable 02 Nov 2011 4 library linking on page 33 to update examples Updated Table 7 on page 65 to correct the description of MME_TUNEABLE_TRANSFORMER_TIMEOUT to quote milliseconds instead of microseconds Updated Section 5 2 1 ICS configuration and setup on page 112 to correctly reference BSP Updated Section 5 5 Memory region management on page 119 to describe memory mapping for the ARM Cortex A9 cores added Figure 11 on page 121 Minor rewordings not listed Updated Chapter 1 Building Multicom on page 8 and Section 1 1 2 Compiler recommendations on page 9 to add STLinux releases and footnote Updated Section 1 4 Compiling and linking against the Multicom 4 libraries on page 17 to remove inappropriate note 24 Jan 2011 c Corrected typo in Section 1 7 Running the tests under OS21 on page 13 Updated Section 2 5 2 Manually managing data buffers on page 24 to correctly refer to the function MME_RegisterMemory rather than MME RegisterBuffer Updated Section 2 11 1 OS21 on page 32 to clarify Documented the BSP_INCDIR environment variable in Appendix A ICS board support package on page 207
55. or the companion refer to MME CommandStatus_t definition Size in bytes of the associated parameter array typically obtained using MME_ LENGTH BYTES Pointer to an allocated parameter array that contains information required to perform the requested operation 3 UM1112 MME API MME_CommandCode _t Constant used by MME_Command_t defines command code Definition include lt mme h gt typedef enum MME SET GLOBAL TRANSFORM PARAMS MME TRANSFORM MME SEND BUFFERS MME _CommandCode_t Description Defines the code of the command to be executed onto the MME The MME SET GLOBAL TRANSFORM PARAMS is defined in order to limit communication between host and companion by setting common parameters that will be shared by the next transformations This command code is to be called only when those common parameters change and to send changes to the companion Parameters which are transformation specific should be part of the parameters of the MME _ TRANSFORM command Fields MME SET GLOBAL TRANSFORM PARAMS Set generic parameters for a specific transformer for subsequent transform requests Those parameters will be used by the transformer until parameters are changed by another call to set generic parameters MME TRANSFORM Commence a transform operation that is process data according to the current context and the parameters associated with the command MME SEND BUFFERS Provide input and or output buffers See
56. parent module if one is specified The functions return a module handle for use as a parent in subsequent load operations or for use by ICS_dyn_unload 8182595 Rev 5 ky UM1112 Overview of the inter core system ICS 5 8 Note 3 When a dynamic module is loaded the ICS system automatically calls a module_init entry in the loaded module if present On unloading a module_term entry is called if present CPU watchdog support ICS supports a requirement to detect and recover from software failures on companion CPUs during execution typically to be managed by the application on the master CPU The scenario supported is when one of the companion CPUs stops operating and communicating as a result of a software failure The recovery action required is typically for the master to reload and restart the companion CPU and then re establish the ICS connections while the rest of the ICS system continues to run The ICS_cpu_init Call takes a flag ICS_INIT_WATCHDOG which installs a system watchdog callback for each CPU present This watchdog will be triggered whenever a CPU failure is detected and it will automatically call ICS_cpu_disconnect ICS also provides functions to install and manage a watchdog monitoring a set of CPUs for failure and functions for disconnecting from a failed CPU and then re connecting after it has been re initialized A watchdog is triggered whenever one of the monitored CPUs fails to update an internal c
57. port _cpu canbe used to return the logical CPU number associated with the 3 supplied port handle If the port handle is valid then ICS_SUCCESS is returned and the associated logical CPU number is returned port should be a valid port handle cpuNump should be a pointer to an ICS_UINT sized object in which the associated CPU number is returned on success 8182595 Rev 5 187 224 Inter core system ICS API UM1112 ICS_port_free Free and close an ICS port Definition Arguments Returns Errors Context Description 188 224 include lt ics h gt ICS_ERROR ICS port free ICS PORT port ICS_UINT flags port Port handle flags Various flag bits which affect behavior ICS SUCCESS Successfully freed port ICS NOT _INITIALISED ICS not initialized ICS PORT _CLOSED Port is already closed ICS HANDLE INVALID An invalid port handle was supplied ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Callable from task context only ICS port free will free off and close a port previously created with ICS port _alloc Closing a port will cause any tasks blocked on the port to be awoken and returned with the ICS_PORT_CLOSED error status For named ports they will also be de registered from the global name server port should be a valid port handle Currently no flags bits are defined and this parameter must be set to zero 3 8182595 Rev 5
58. process and interrupt based data reception are provided See Figure 8 Channels provide the lowest overhead and lowest latency communications within the ICS system As such the programmer is responsible for all protocol handling and flow control Figure 8 ICS channels CPU 0 lot si j Slot size n slots gt CPU 1 CPU 2 Gin ee CPU 3 m No equivalent low level API was provided in previous versions of Multicom causing a number of alternative very low level communication libraries to be written for different applications the intention here is to provide this low level of communication in a standardized form Table 15 Channel functions in ICS Function name Description Ics_channel_alloc Allocate an ICS communication channel ICS_channel_free Free an ICS channel IcCsS_channel_open Open a send channel for communication IcCs_channel_close Close a send channel ICS_channel_send Send a buffer using an ICS send channel ICS_channel_recv Blocking call to receive a buffer from an ICS channel ICS channel release Release an ICS channel FIFO buffer ICS channel unblock Unblock a blocked ICS channel 8182595 Rev 5 115 224 Overview of the inter core system ICS UM1112 116 224 ICS channel alloc is called on the CPU that is to be the receiving end of
59. released and cannot be used again ICS_msg_cancel must not be called on message events which are currently being blocked on in a call to ICS_msg wait If the associated port is closed with ICS_port_free whilst there are still outstanding posted receives then they will all be automatically released Calling ICS _msg_cancel on such handles will result in ICS HANDLE INVALID being returned event should be a valid message event handle 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_MSG_DESC Port message descriptor Definition include lt ics h gt typedef struct ics_msg desc ICS OFFSET data ICS SIZE size ICS MEM FLAGS mflags ICS UINT srcCpu ICS CHAR payload ICS MSG INLINE DATA ICS_MSG_DESC Members data Address of the message data buffer size Size in bytes of the receive message mflags Memory attribute flags of the data buffer srcCpu CPU number of the source CPU payload Area for ICS_ INLINE data Description This is the message descriptor posted and completed by ICS_msg_recv and 3 ICS_msg_post On successful completion all the member fields will have been completed by the ICS system data will be a valid address of the corresponding data buffer In the case of ICS_INLINE ICS_CACHED and ICS_UNCACHED messages this will be a corresponding virtual address pointer For ICS_PHYSICAL messages it will be a physical memory address size Will be the size of the received message in bytes
60. source code for the ICS implementation source src mme Complete source code for the MME implementation test src include C header files used by test suite test src tests ics Test suite for the ICS subsystem test src tests mme Test suite for the MME subsystem lib lt os gt lt arch gt Compiled libraries for each OS and SoC bin lt os gt lt arch gt Compiled test codes for each OS and SoC 1 Created when Multicom 4 is built 3 8182595 Rev 5 UM1112 Building Multicom Note 1 2 Note 3 All makefiles supplied with Multicom use GNU make syntax Therefore in order to rebuild the distribution run the test suites or build any example then a version of make compatible with GNU make must be available All target resident code supplied with Multicom is provided in source form to facilitate debugging and porting Compiler recommendations The Release Notes provide the list of products for which Multicom 4 has been tested Several issues have been found when using Multicom with the ST200 Micro Toolset R6 3 0 In addition issues have been found using the GNU make tool under Windows so GNU make 3 81 or later is recommended Building the library code The source directory must be built first before any of the tests are built For OS21 builds makefiles are provided for each CPU architecture For example to build Multicom 4 for ST40 and ST200 issue the following commands cd source
61. task context it is allowed to call any of the ICS task context functions 3 8182595 Rev 5 197 224 Inter core system ICS API UM1112 ICS_watchdog remove Remove a previously installed watchdog callback Definition Arguments Returns Errors Context Description 198 224 include lt ics h gt ICS_ERROR ICS watchdog remove ICS WATCHDOG handle handle Handle of watchdog to be removed ICS SUCCESS Successfully removed the watchdog callback ICS HANDLE INVALID An invalid handle was supplied ICS SYSTEM ERROR A system error occurred Callable from task context only ICS watchdog remove removes a previously installed watchdog callback handler All further watchdog triggers of the monitored CPUs will be ignored handle should be a valid watchdog handle as allocated by ICS_watchdog_add 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_watchdog_reprime Reprime a triggered watchdog callback Definition include lt ics h gt ICS ERROR ICS watchdog _reprime ICS WATCHDOG handle ICS UINT cpuNum Arguments handle Handle of watchdog to be re primed cpuNum Logical CPU number of the CPU to monitor Returns ICS SUCCESS Successfully re primed the watchdog Errors ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid handle was supplied ICS SYSTEM ERROR A system error occurred Context Callable from task context only Description ICS watchd
62. the callback function ndesc Depth of message queue for this port flags Various flag bits which affect behavior portp Port handle pointer used to return allocated handle ICS SUCCESS Successfully allocated port portp Allocated port handle ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Callable from task context only ICS _port_alloc allocates an ICS port on the local CPU Ports can either be anonymous or named All named ports are registered with the global name server from where they can be discovered and communicated with by all participating CPUs If the supplied portName is already present in the name server then multiple port handles with the same name will be registered and returned in a round robin order on lookup portName is an optional ASCII o terminated string of length not exceeding ICS PORT MAX NAME characters not including the 0 portName can be set to NULL to indicate that this is a local anonymous port whose name does not need to be registered with the global name server 8182595 Rev 5 ky UM1112 Inter core system ICS API callback is a pointer to function of type ICS_ PORT CALLBACK which will be invoked each time a new message arrives at the port It will be invoked in interrupt contex
63. the physical address of the supplied virtual data buffer to be presented at the target port In this case the data buffer does not need be have been pre registered with ICS_region_add Using the zero copy message passing technique effectively transfers ownership of the physical data region to the target CPU ICS does not take any further control in this respect and therefore it is the programmer s responsibility to ensure the memory is correctly managed and released on the sender ICS _msg_send is an asynchronous nonblocking operation and on return it cannot be assumed that the target CPU has received the message This means that except in the case of ICS_INLINE messages the supplied data buffer cannot be reused until some form of acknowledgement has been received from the target CPU The valid flags bits are defined in Table 27 Table 27 ICS message send flag Channel flag Description ICS MSG CONNECT Make a connection to target CPU if necessary Setting the flag bit value ICS_MSG CONNECT causes the ICS system to attempt to make a connection to the target CPU if one if not already in place If the CPU has failed then this operation blocks and the call eventually returns an error after a predefined timeout period It is advised that the ICS_MSG_CONNECT flag should be used whenever a new connection is being potentially established with the target CPU especially when the ICS _INIT_CONNECT_ALL flag was not passed to ICS_
64. this document supersedes and replaces all information previously supplied The ST logo is a registered trademark of STMicroelectronics All other names are the property of their respective owners 2013 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com 224 224 8182595 Rev 5 ky
65. transformer execution loop actions MME DBG COMMAND Log all transformer command actions MME DBG BUFFER Log all MME data buffer actions See also MME_DebugFlags kyy 8182595 Rev 5 91 224 MME API UM1112 MME_ERROR Status indicator used by all MME functions Definition include lt mme h gt typedef enum MME_ SUCCESS MME_DRIVER_NOT INITIALIZED MME_NOMEM MME INVALID HANDLE MME_INVALID ARGUMENT MME_UNKNOWN_TRANSFORMER MME_ TRANSFORMER _NOT_ RESPONDING MME HANDLES STILL OPEN MME COMMAND STILL EXECUTING MME _ COMMAND ABORTED M M M M M M M M s ME DATA _UNDERFLOW ME DATA OVERFLOW ME TRANSFORM DEFERRED ME SYSTEM INTERRUPT ME ICS ERROR ME INTERNAL ERROR ME NOT IMPLEMENTED ME COMMAND TIMEOUT MME _ ERROR Description Status indicator used by all MME functions Note Although MME_SUCCESS is guaranteed to be zero the numeric value of all other error codes is unspecified Additionally it is not guaranteed that these values will be contiguous Fields MME SUCCESS Command complete successfully MME _DRIVER_NOT_INITIALIZED MME or some of its underlying infrastructure has not yet been initialized MME_DRIVER_ALREADY_ INITIALIZED MME has been initialized already MME _NOMEM The system has insufficient resources to complete this request MME INVALID HANDLE The transformer handle is invalid or out of date MME INVALID ARGUMENT One or more of the function arguments are
66. 0 2 9 2 Providing supplementary buffers 0 00 0 eee 30 2 9 3 Altering global parameters 0 0000 ees 30 2 10 Common types of transformer 000 eee 31 2 10 1 Frame based operation 02000 cece eee 31 2 10 2 Stream based and hybrid operation 00 c eee eee 31 2 11 Linking and loading a are da nd neces cas nse hence com a acne alata Gar aah accede ie 32 241A OSZT 4 2ccddas pitied pha ptarnieedar a aie e o debe a 32 2112 INU seresa bend Poe hea eh a ceeded eet anes A danas 32 2 11 3 Relocatable library linking 0 cee ee 33 3 Writing an MME transformer 0000 eee eee eee 34 3 1 OVEIVIEW irran mracna mop oad eco a wan eee bee ede a ee a aN E eae 34 3 2 Managing transformer lifetimes 0 0 00 35 3 2 1 Instantiation 2c scekieee tad etd eee nec e ae a eed ans 35 3 2 2 Context data ce sacks dakari dai no wade sh sco ae ae aa ee ae 35 3 2 3 TERMINATION 4 2 ee eas et ee ee ee ae E 36 3 3 Querying the capabilities of a transformer 2 36 3 4 Processing a command 2122s snake n wenn daweeee dwar Reka kamen 38 3 4 1 Communicating with the application 22200000 39 3 4 2 Deferred commands 000 e eee tenes 40 3 4 3 Streaming and hybrid transformers 0 0 000 eee eee eee 41 ky 8182595 Rev 5 3 224 Contents UM1112 3 5 Aborting commandS 2 025 co cenegeewne en aacdo cubase hae haw eux 42 3 6 S
67. 1112 MME_GenericParams_t Type for data exchange between CPUs Definition include lt mme h gt typedef void MME GenericParams_t Description Generic type used to exchange data between host and companion CPUs Fields None See also MME_Command_t 3 96 224 8182595 Rev 5 UM1112 MME API MME_GetTransformerCapability_t Provide transformer capabilities Definition include lt mme h gt MME ERROR MME GetTransformerCapability t MME TransformerCapability t capability Arguments capability Transformer parameters Returns MME SUCCESS Success MME INVALID ARGUMENT An invalid transformer parameter has been specified Description Provide the capabilities of a transformer Comments Call type blocking function call See also MME_GetTransformerCapability 3 MME_ TransformerCapability_t 8182595 Rev 5 97 224 MME API UM1112 MME_InitTransformer_t Create a transformer instance Definition include lt mme h gt MME ERROR MME InitTransformer_t MME UINT size MME GenericParams_t params void context Arguments size Size of the transformer initialization parameters in bytes params Transformer initialization parameters context Pointer to a location in which to store a transformer instance specific value Returns MME SUCCESS Success MME INVALID ARGUMENT An invalid transformer parameter has been specified MME _NOMEM Insufficient memory available Description Create an instance of a trans
68. 12 13 124 137 command state 621 0660 se0se sc anna 28 ICS_dyn_load_file 122 165 commands 18 27 31 38 44 ICS_dyn_load_image 122 167 deferred oes asri dewedacimesed ci aw don 40 ICS_dyn_unload 0 122 169 GONIEM data esce bata aawew eeeseands as 35 ICS CM SU ji ke ee a ee tau 113 139 data representation 00 44 ICS_ERROR 22s seen eee eee 116 118 due Me 28 eva Peed Gowen Pee tae ats 18 ics_heap_alloc 2 sees 114 140 initialization 00 2 0c eee 20 ics_heap_base 4 114 141 insufficient memory 00 42 ics_heap_create 114 142 Namespace 0 cece eee eeeeseee 47 ics_heap_destroy 114 143 parameter passing o u onunu 44 ics_heap_free 20 eae 114 144 underflow cece eee cece 42 ics_heap_pbase athe Siege er eee Gets 114 145 MME_AbortCommand 29 32 51 ics_heap_size Queer a See aaa 114 146 MME AbortCommand t 42 44 79 ics_load_elf_fle 113 147 MME_AllocationFlags t 000 00 80 ics_load_elf_image 113 148 MME_AllocDataBuffer 24 52 ics_load_free 00 0 149 MME Command t 27 43 81 ICS_msg_cancel 117 118 170 MME CommandCode t 83 CS MSG DESC onlann auaa 171 MME CommandEndType i 1 40 c
69. 3 8182595 Rev 5 219 224 Revision history UM1112 Table 34 Document revision history continued Date Revision Changes Supports the Multicom 4 R4 0 2 Removed all references to ics _load_entry and ics load_free Added details about Linux userspace to Chapter 1 Building Multicom on page 8 throughout Updated Table 1 on page 8 Updated Section 1 1 2 Compiler recommendations on page 9 Updated the Notes in Section 1 4 Compiling and linking against the Multicom 4 libraries on page 11 Updated Section 1 6 Debugging support on page 12 and added Section 1 6 1 Debug logging on page 13 Updated Section 1 8 Running the tests under Linux on page 13 Updated Section 2 1 1 Transformers and transformer instances on page 15 and added Figure 2 Moved multi hosting material to Section 2 1 2 Multi hosting support on page 16 and added Figure 3 Added Section 2 8 Fault detection and recovery on page 29 Added MME_PingTransformer on page 70 Updated the description of MME_WaitCommand on page 76 Added MME_COMMAND_ TIMEOUT to MME_ERROR on page 92 Added MME_TRANSFORMER_TIMEOUT to MME_Event_t on page 94 Updated Table 10 on page 113 and associated text 29 Jun 2010 5 Updated Section 5 2 3 ICS initialization and termination on page 114 Added Note to Section 5 8 CPU watchdog support on page 123 Updated the description of ics_cpu_init on page 126 adding Table 22 Updated the definition and error of ics_cpu_
70. 4 Inter core system ICS API UM1112 ics_heap_free Release a buffer back to an ICS heap Definition Arguments Returns Errors Context Description 144 224 include lt ics h gt ICS ERROR ics heap free ICS HEAP heap ICS VOID buffer heap Heap handle buffer Buffer address ICS SUCCESS Successfully freed buffer ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid handle was supplied ICS SYSTEM ERROR A system error occurred Callable from task context only Can be called before ICS_cpu_init ics heap free returns a previously allocated buffer to the heap The buffer address supplied must be the exact one supplied by ics heap alloc heap should be a valid ICS heap handle and be associated with the returned buffer address buffer should be a valid address previously returned by ICS_ heap _alloc 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_heap_pbase Query ICS heap for physical base Definition include lt ics h gt ICS OFFSET ics heap pbase ICS HEAP heap Arguments heap Heap handle Returns Associated heap parameter Errors ICS BAD OFFSET Physical base address of heap not found Context Callable from task context only Can be called before ICS_cpu_init Description ics heap pbase returns the physical address base of the supplied ICS heap This is one of three functions that allow the caller to query the base and size of
71. 56 ss PREM E SE Ee ss bes ac tee Eeaee a a 6 US TMM MN OY sess sient chen ate sean e aa een cetera et lage Ron oe ote pedis gata cota 6 Conventions used in this guide 0 0 6 es 6 ACknOWwIEdQeMGINS is cad evden ee awe bv ew Gesvewe wba ecanee deeb aates 7 1 Building Multicom 2 0 idwesessee eee oe weds wie teal he dede ee 8 1 1 OVEIVIOW cress presensi ee ee Ee ea ee a a ee ae et 8 1 1 1 Code organization 0 2c eee 8 1 1 2 Compiler recommendations 0000 cece eee eee 9 1 2 Building the library code 2 2 0 0 cc ees 9 1 3 Building the test code 2 ee eee 10 1 4 Compiling and linking against the Multicom 4 libraries 11 1 5 Building relocatable libraries for use with Multicom 4 11 1 5 1 Relocatable library tool 00 00 cece eee eee 12 1 6 Debugging support gaa oc ha he Kee de ae Wah eer pee ae de he Oe ered 12 1 6 1 Debug logging 2 0 c eee eee 13 1 7 Running the tests under OS21 2 2 ee 13 1 8 Running the tests under Linux 0 00 e eee eee 13 1 9 BSP configuration 2 35 een drat end Regeek eee ek he R ea hewn eRe a Rea x 14 2 Using the MME API ci cccccs ca ceeadcaeetadeeaseevednweck eee s 15 2 1 Overview 2 01 tte ete 15 2 1 1 Transformers and transformer instances 00000 ee eee 15 2 1 2 Multi hosting support 0 0000 eee 16 2 1 3 Commands and events 0 0 cece eee tee 18
72. 7 Note Note 3 7 1 44 224 however for transformers to protect access to any variable or list that is manipulated by multiple threads Transformers that do not support MME_SEND_ BUFFERS or MME AbortCommand_t are implicitly thread safe Parameter passing Many of the MME functions take transformer specific parameter blocks specified in MME structures as MME _GenericParams_ t see Section 2 6 Application and transformer specific data on page 27 In each case the parameter block is described using a pointer to a generic 64 bit type and a size in bytes Transformers that require parameters to correctly process their input typically specify parameters in a header file shared by the application It is not possible for a parameter block to contain pointers to other data because it may not be possible to dereference these pointers on other processors On systems with identical endianness the parameter block is presented byte for byte identically as it passes between the application and the transformer However on mixed endian systems the parameter block will be treated as an array of 64 bit quantities each of which will be byte swapped in 64 bit units For example the 64 bit hexadecimal integer 0x0011 2233 4455 6677 would after swapping become 0x7766 5544 3322 1100 if it were examined on the originating processor It is the transformer s responsibility to define its parameter block in such a way that it may be safely passed between p
73. 8182595 Rev 5 UM1112 MME API MME_InitTransformer Initialize an instance of a transformer Definition include lt mme h gt MME ERROR MME InitTransformer const char Name MME TransformerInitParams_t Params_p MME TransformerHandle t Handle_ p Arguments Name Name of the transformer registered with MME RegisterTransformer Params_p Pointer to an allocated MME TransformerInitParams_t that contains the parameters with which the transformer will be initialized Handle p Pointer to an MME_TransformerHandle _t that will contain the handle of the initialized transformer Returns MME SUCCESS The device has been successfully initialized MME DRIVER_NOT_INITIALIZED The MME driver has not been initialized MME NOMEM The memory required to complete this command is not available MME UNKNOWN TRANSFORMER No transformer of the specified name exists MME INVALID ARGUMENT Params_p or Handle pis invalid Description Creates and initializes an instance of a specific transformer on a CPU The name argument must not be longer than MME_MAX TRANSFORMER_NAME bytes The error code MME INVALID ARGUMENT will be returned if the name is too long The name of the transformer implicitly describes the type of that transformer for example STAC3DecoderMacro This can be confirmed by using MME GetTransformerCapability to examine the capability of transformer if required If the host has to synchronize with transformer re
74. ALID ARGUMENT MME never attempts to terminate a transformer with outstanding commands Any command that is unable to complete without some further action being performed on the transformer must support aborts 3 8182595 Rev 5 UM1112 Writing an MME transformer Some examples of commands that are required to support abortion include e allMME_SEND_ BUFFERS commands e commands blocked after data underflow or overflow e pipelined commands Commands are marked as aborted by one of the following methods e by returning MME_ SUCCESS from MME_AbortCommand_t e by calling MME_NotifyHost with the event code MME __COMMAND_EVT and the error code MME COMMAND ABORTED by returning MME COMMAND ABORTED from MME Process Command t The call to MME_NotifyHost can be made from any thread including the abort function the processing function or from asynchronous threads owned by a deferred transformer Note When aborting a command using any of the above methods the transformer guarantees that the following conditions are met e No further execution time is spent on the command e No further use is made of any part of the MME_Command_t structure including data buffers This means that no further calls to MME_NotifyHost are made e No further attempt is made to mark the command aborted Thus if MME AbortCommand_t calls MME _NotifyHost or expects the currently executing command to read from the command structure or to return any value except MME TRANSF
75. ARAM 59 ICS_VERSION_CODE 5 20 MEM aint so nates shedna tonne 21 60 ICS_watchdog_add 123 195 MME_InitTransformer 22 23 61 ICS_WATCHDOG_CALLBACK 197 MME_InitTransformer_t 35 98 ICS_watchdog_remove 123 198 MME_IsTransformerRegistered 62 ICS_watchdog_reprime 123 199 MME LENGTH 222 0 63 222 224 8182595 Rev 5 ky UM1112 Index MME_LENGTH_BYTES 64 S MME_MAX_TRANSFORMER_NAME 99 sh rltool 12 MME_MemoryHandle_t 100 Software 6 6CUCt CSs lt lt lt i lt i lt lt OS MME_ModifyTuneable 65 217 notation 6 MME_NotifyHost 39 40 43 67 Qs MME PARAM 68 Source code 22220e eee eee 8 MME_PARAM SUBLIST aes eee 69 ST Micro Connect 0 5 6 MME_PingTransformer 70 st20Orltool 1 ee 12 MME Priority_t O 101 Stream based transformer 31 MME_ProcessCommand_t 38 43 102 MME_RegisterMemory 24 71 T MME_RegisterTransformer 21 34 72 Transformer MME_ScatterPage t 26 103 See also MME DIE SEND BUER ERS eric cineece sei cass 3A SEAIIDEEK 2 nen ganctnamae ania ttiig ehi 18 MME_SEND_BUFFERS 18 30 31 39 41 43 44 commands See MME MME _SendCommanrd 24 27 30 38 73 commands MME_SET_GLOBAL_TRANSFORM_PARAMS
76. CS CACHED ICS UNCACHED or ICS PHYSICAL addressp should be a valid pointer to an ICS_VOID pointer 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_region_remove Remove a region from the local and remote CPU region tables Definition include lt ics h gt ICS_ERROR ICS region_remove ICS REGION region ICS _UINT flags Arguments region Region handle flags Various flag bits which affect behavior Returns ICS SUCCESS Successfully removed region Errors ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid region handle was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Context Callable from task context only Description ICS region _remove removes and un maps a memory region on both the local CPU and all the remote CPUs as specified in the original IcS_region_add call region should be a valid region handle as returned by ICS_region_add No flags bits are currently defined so this parameter must be set to zero 3 8182595 Rev 5 193 224 Inter core system ICS API UM1112 ICS_region_virt2phys Translate a local virtual address into a physical one Definition Arguments Returns Errors Context Description 194 224 include lt ics h gt ICS_ERROR ICS region _virt2phys ICS
77. Cheale ois Ga cacended aiiee beac eas 22 35 18 2 eee eee tees 30 39 43 GOSHOY caencd db aheeend otha dd aha ead 22 MME_Term 20 essen eee eee 74 evento rero aea e E caride 18 MME_TermTransformer 22 75 frame based 22 31 39 MME_TermTransformer_t 36 104 instance i id ewes RAW oe we EK Bane 45 MME_Time_t 0 0s esse eee 105 instantiation 000002220000 e 35 MME_TRANSFORM 18 30 32 39 43 pipelined 0 0 cee eee 40 MME_TransformerCapability t 106 priorities sorrera nest wees EE an 19 MME_TransformerHandle t 107 UEY nad kd Sian nats Seance Secs 23 36 MME_TransformerinitParams t 108 registering o oo aoon 24 34 MME_UNIT ge eee dees A oer eee ee 109 stream based 220200000 31 MME_Version 00 sees ee eeee 78 termination cise cAseaenakeoa eames 36 MME_WaitCommand 76 Ype it anc emotes woud eee seen ad eases 31 module parameters 218 Tuning parameters 00e0 eee 217 module _init 000005 123 module_term 2020000 eee 123 MPGV_DecodeParams t 214 MPGV_GlobalParams t 212 MPGV_PictureType t 211 multi hosting 220000005 16 N Namespace MME sscctnds ve Sart aed nate ea S 47 O OS21 iene how A ea as 9 10 13 R Relocatable libraries
78. DLE INVALID An invalid send channel handle was supplied ICS SYSTEM ERROR A system error occurred Context Callable from task context only Description ICS channel _close closes a send channel that was previously opened using ICS_channel_ open Any channel sends currently in progress will still be delivered to the receiving channel schannel should be a valid send channel handle 3 152 224 8182595 Rev 5 UM1112 Inter core system ICS API ICS_channel_free Free an ICS channel Definition include lt ics h gt ICS_ERROR ICS channel free ICS CHANNEL channel ICS_UINT flags Arguments channel Channel handle flags Various flag bits which affect behavior Returns ICS SUCCESS Successfully freed channel Errors ICS NOT _INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid channel handle was supplied ICS SYSTEM ERROR A system error occurred Context Callable from task context only Description ICS channel free frees a local CPU channel previously allocated with 3 ICS_channel_alloc Freeing a channel will cause all resources associated with it to be freed and also any tasks blocked on the channel to be awoken Any unprocessed entries in the FIFO will be ignored channel should be a valid channel handle Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 153 224 Inter core system ICS API UM1112
79. DOG CALLBACK ICS WATCHDOG handle ICS VOID param ICS _UINT cpuNum ICS VOID param ICS _ULONG cpuMask ICS UINT flags ICS WATCHDOG handlep callback param cpuMask flags handlep ICS SUCCESS handlep ICS NOT _INITIALISED ICS INVALID ARGUMENT ICS ENOMEM ICS SYSTEM ERROR ICS ERROR ICS watchdog _add ICS WATCHDOG CALLBACK callback Callback function for this watchdog Parameter to be supplied to the callback function Bitmask of all logical CPUs to be monitored Various flag bits which affect behavior Handle pointer used to return allocated handle Successfully installed the watchdog Contains allocated watchdog handle ICS not initialized An invalid argument was supplied Failed memory resource allocation A system error occurred Callable from task context only ICS watchdog_add installs a new CPU watchdog callback The CPU watchdog system will continuously monitor the CPUs as indicated by the cpuMask bitmask If any one of these CPUs crashes or is reset then the callback function will be called Multiple watchdog callbacks can be installed and it doesn t matter if the set of CPUs they are monitoring overlaps When a CPU failure occurs all watchdog callbacks monitoring the failed CPU will be called Once the callback has been triggered for a particular CPU it will not trigger again until ICS watchdog _reprime has been called for that particular CPU Using this technique means that if
80. Defines valid states for a command Definition include lt mme h gt typedef enum MME COMMAND PENDING MME COMMAND EXECUTING MME COMMAND COMPLETED MME COMMAND FAILED MME _CommandState t Description Defines the different states a command may have See Section 2 7 Issuing commands on page 27 Fields MME COMMAND PENDING Command waiting to be processed by the MME MME COMMAND EXECUTING The command is the currently executed by the MME MME COMMAND COMPLETED The command has been completed by the transformer and results are available for the application MME COMMAND FAILED Errors occurred during command processing by the transformer or by MME See also MME_Command Status_t 3 86 224 8182595 Rev 5 UM1112 MME API MME_CommandsStatus_t Definition Description Fields 3 Note Sub structure to MME_Command_t returns transformation results include lt mme h gt typedef struct MME CommandId_t CmdId MME CommandState _t State MME Time_t ProcessedTime MME _ ERROR Error MME _UINT AdditionalInfoSize MME GenericParams_t AdditionaliInfo p MME _CommandStatus_t Structure filled by MME with the results of the corresponding transformation actions performed With the exception of the additional parameters all members of the MME CommandStatus_t are populated by the MME as part of MME_SendCommand MME CommandStatus_t s not supplied directly to any MME API call it forms part of t
81. ICS API UM1112 ICS_debug_dump Dump out the debug log Definition include lt ics h gt ICS ERROR ICS debug dump ICS _UINT cpuNum Arguments cpuNum Logical CPU number Returns ICS SUCCESS Successfully dumped the log Errors ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS NOT _CONNECTED Target CPU is not connected ICS SYSTEM ERROR A system error occured Context Callable from task context only Description ICS debug dump dumps out all the log messages for the logical CPU cpuNum When linked against the debug ICS libraries each subsystem can be set to log messages by calling the ics debug flags function If the debug channel has also been set using ics debug _chan to enable logging to the cyclic buffer then these messages will be displayed by calling this function 3 164 224 8182595 Rev 5 UM1112 Inter core system ICS API ICS_dyn_load_file Load a dynamic ELF module from a local file Definition include lt ics h gt ICS ERROR ICS dyn load file ICS _UINT cpuNum ICS CHAR fname ICS UINT flags ICS_ DYN parent ICS DYN handlep Arguments cpuNum Target CPU number fname Local OS filename of the dynamic ELF module flags Various flag bits which affect behavior parent Dynamic object handle of parent module handlep Returns dynamic module handle Returns ICS SUCCESS Successfully loaded the dynamic module handlep Allocated dynamic module handl
82. ITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT ST PRODUCTS ARE NOT DESIGNED OR AUTHORIZED FOR USE IN A SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS B AERONAUTIC APPLICATIONS C AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS AND OR D AEROSPACE APPLICATIONS OR ENVIRONMENTS WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE THE PURCHASER SHALL USE PRODUCTS AT PURCHASER S SOLE RISK EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR AUTOMOTIVE AUTOMOTIVE SAFETY OR MEDICAL INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS PRODUCTS FORMALLY ESCC QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in
83. ME GetTransformerCapability t MME TransformerCapability_t capability MME GetTransformerCapability_t is called as a result of an application call to MME GetTransformerCapability see Section 2 4 1 on page 23 This function pointer is not provided with a context pointer because it is used to describe the capabilities of the abstract transformer rather than that of a specific transformer instance If the capability structure capability or the transformer specific parameter block it contains is in some way incorrect then MME_GetTransformerCapability t should return an error Otherwise it should populate MME_TransformerCapability_t and if applicable its transformer specific parameter block capability The generic information a transformer must provide is its version number which can be any 32 bit integer and its preferred input and output data format in four character code FOURCC format see MME_DataFormat_t on page 90 for more details For most transformers the application knows the size of the parameter block in advance Storage must be provided by the application Such transformers should return an error if the parameter block is incorrectly sized In order to cope with transformer specific parameters of a variable size the transformer must provide a means for the application to query how much memory it should provide for the parameters to be correctly stored There are many ways this could be achieved The recommended approach i
84. MME DeregisterMemory MME FreeDataBuffer MME DeregisterTransformer MME GetTransformerCabability MME DeregisterTransport MME GetTuneable MME ErrorsStr MME Init MME NotifyHost MME _InitTransformer MME PingTransformer MME _IsTransformerRegistered MME RegisterMemory MME ModifyTuneable MME_SendCommand MME RegisterTransformer MME RegisterTransport MME Term MME_ Run MME TermTransformer MME Version MME WaitCommand 8182595 Rev 5 3 UM1112 MME API 4 1 Function definitions This section provides detailed descriptions of the MME functions The functions are listed in alphabetical order MME_AbortCommand Abort command submitted to transformer Definition include lt mme h gt MME ERROR MME AbortCommand MME TransformerHandle t Handle MME CommandId_t CmdId Arguments Handle Handle of the targeted transformer CmdId Command identity of the command to abort Returns MME SUCCESS An abort request has been submitted this does not imply the command has been aborted MME DRIVER_NOT INITIALIZED The MME driver has not been initialized MME INVALID HANDLE The transformer handle is invalid MME_ INVALID ARGUMENT The CmdTd is invalid Description Attempt to abort a command that has been submitted to a transformer The behavior of this function is transformer and implementation specific Commands can always be aborte
85. NITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS NOT CONNECTED Target CPU is not connected ICS SYSTEM ERROR A system error occurred Callable from task context only ICS _cpu_disconnect disconnects from a logical CPU so that it can no longer be communicated with This call also frees up all local and remote resources associated with that CPU connection ICS_cpu_disconnect should be called when a CPU fails or crashes doing so will then enable a new connection to be made once the CPU has been restarted cpuNum is the logical CPU number for which the disconnection is required Setting the ICS_CPU_DEAD bit of flags causes the disconnect to avoid communicating with the failed CPU This bit should be set in the case of disconnecting from a failed CPU Setting the ICS_INIT_WATCHDOG bit value in the call to ICS_cpu_init or ics cpu_init enables an automatic callback when a CPU failure is detected In the case of a failure ICS_cpu_disconnect is called automatically for the failed CPU 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_cpu_info Query the ICS CPU configuration Definition include lt ics h gt ICS_ERROR ICS cpu_info ICS UINT cpuNump ICS ULONG cpuMaskp Arguments cpuNump Return parameter for CPU number cpuMaskp Return parameter for CPU mask Returns ICS SUCCESS Call was successful Errors ICS NOT _INITIALISED ICS is not initialized ICS I
86. NVALID ARGUMENT Invalid arguments supplied Context Callable from task and interrupt context Description ICS _cpu_info queries the CPU info of the currently running ICS system On success the ICS CPU number of the current CPU and a bitmask representing each CPU present will be returned using the supplied parameters In the returned bitmask each set bit n represents that logical CPU number n is present cpuNump should be a valid pointer to an ICS_UINT sized object in which the logical CPU number will be returned cpuMaskp should be a valid pointer to an ICS_ULONG sized object in which the logical CPU bitmask will be returned 3 8182595 Rev 5 161 224 Inter core system ICS API UM1112 ICS_cpu_init Definition Arguments Returns Errors Context Definition 162 224 Initialize the ICS system on a CPU include lt ics h gt ICS ERROR ICS cpu_init ICS _UINT flags flags Various flag bits which affect behavior ICS SUCCESS Successfully initialized ICS ALREADY INITIALISED ICS is already initialized ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to synchronize with other CPUs Callable from task context only ICS _cpu_init is the recommended function for initializing the ICS and should be used to start the ICS system on each participating CPU It must be called before any of the other Ics_ functions are called It sh
87. OR A system error occurred ICS SYSTEM TIMEOUT Failed to synchronize with other CPUs Context Callable from task context only Definition ics cpu_init is provided primarily for debugging purposes where a subset of CPUs is being tested For example just a pair of CPUs could be specified in the bitmask It is recommended that the function CS_cpu_init on page 162 is adopted as the usual method of initializing the ICS system ics cpu_init canbe called to start the ICS system on each participating CPU If used it must be called before any of the other Ics__ functions are called It should be called from a task context and only be called once per CPU cpuNum is the logical CPU number of the calling CPU ics_cpu_self canbe used to determine this value cpuMask is a bitmask of all the required CPUs this can be a subset of all the CPUs on the SoC The set of valid debug channel flag bits are detailed in Table 22 Table 22 ics_cpu_init flags Init flag Description ICS _INIT_CONNECT_ALL Connect to all CPUs in the bitmask during initialization ICS INIT WATCHDOG Enable the CPU watchdog for all CPUs in the bitmask 126 224 8182595 Rev 5 ky UM1112 Inter core system ICS API Setting the flag bit value ICS INIT CONNECT ALL in the call to ics cpu_init causes the calling CPU to attempt to connect and synchronize with all the other CPUs which are present in the supplied CPU bitmask It blocks until all the other CPU
88. ORM DEFERRED then the abort command must itself return MME TRANSFORM DEFERRED Thus MME _AbortCommand_t should return MME_ SUCCESS only if the command has already been aborted and the host has not been notified by another means 3 6 Scheduling and re entrancy MME utilizes multiple threads and it is important that transformer functions are written in such a manner that thread safety is maintained Neither initialization nor termination have any thread safety issues The functions are not re entered nor will any other transformer interface function be called during these operations Note It is a pre condition of the termination function that all outstanding commands complete and 3 this is assured by MME Similarly calls to MME_GetTransformerCapability_t see Section 3 3 on page 36 are serialized For a single instantiated transformer up to three threads can operate over the same context structure at the same time These are e An execution thread that calls the processing function with a command code of either MME TRANSFORM or MME SET GLOBAL TRANSFORM PARAMS e A manager thread that calls the processing function with a command code of MME SEND BUFFERS e Amanager thread that calls the abort function In summary the MME_ProcessCommand_t can be re entered but not with the same command code while MME_AbortCommand_t cannot be re entered It is a requirement 8182595 Rev 5 43 224 Writing an MME transformer UM1112 Note 3
89. RANSFORM and reply Transform TransformStatus MME SendCommand Send SendStatus MME_SEND BUFFERS and reply 3 7 4 An example This example maps the following C structure into MME parameters struct STExampleTransform U32 STExampleTransformNormal U8 STExampleTransformArray 10 struct STExampleSub U32 STExampleSubNormal hi To copy the data listed above as an MME parameter array the transformer would add the following definitions to its header file As a parameter sub list this list does not use the standard postfixes from the table above enum STExampleSub MME OFFSET STExampleSubNormal MME LENGTH STExampleSub define MME TYPE STExampleSubNormal U32 typedef MME GenericParams_t MME STExampleSub t MME_LENGTH STExampleSub enum STExampleTransform MME OFFSET STExampleTransformNormal MME OFFSET STExampleTransformArray MME OFFSET STExampleTransformSublist MME OFFSET STExampleTransformArray 10 48 224 8182595 Rev 5 3 UM1112 Writing an MME transformer MME LENGTH STExampleTransform MME OFFSET STExampleTransformSublist MME LENGTH STExampleSub define MME TYPE STExampleTransformNormal U32 define MME TYPE STExampleTransformArray U8 no need for MME TYPE STExampleTransformSublist typedef MME _GENERIC64 MME STExampleTransform_t MME LENGTH STExampleTransform The following example demonstrates how an application would use the par
90. S _ SUCCESS Successfully unloaded the dynamic module Errors ICS HANDLE INVALID An invalid handle was supplied ICS NOT CONNECTED Target CPU is not connected ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT A communications operation timed out Context Callable from task context only Description ICS dyn_unload unloads a dynamic ELF module which was previously loaded 3 using ICS_dyn_load file or ICS dyn load_image It will unload the dynamic module in the original target CPU making use of the rl toolkit system As a dynamic module is unloaded from the target CPU the ICS system will automatically call a function named module _term if one is present in the loaded module handle should be a valid dynamic module handle 8182595 Rev 5 169 224 Inter core system ICS API UM1112 ICS_msg_cancel Cancel an asynchronous port receive Definition Arguments Returns Errors Context Description 170 224 include lt ics h gt ICS_ERROR ICS msg cancel ICS MSG EVENT event event Message event handle to be cancelled ICS SUCCESS Cancel completed successfully ICS_NOT_INITIALISED ICS not initialized ICS HANDLE INVALID An invalid event handle was supplied ICS_SYSTEM_ERROR A system error occurred Callable from task context only ICS _msg_cancel cancels an asynchronous receive request as posted with ICS _msg_ post On successful return the message event handle will have been
91. S mflags heap Heap from which to allocate the buffer size Size of the buffer in bytes mflags Memory region attributes Non NULL address of the buffer allocated NULL is returned on error Callable from task context only Can be called before ICS_cpu_init ics heap _alloc allocates a buffer of size bytes from a heap previously created with ics heap _create When all resources from the heap are exhausted NULL will be returned Both cached and uncached translations of the heap buffers can be obtained by specifying the relevant flag in the mflags parameter To avoid cache coherency issue between the CPUs all buffers allocated will be ICS CACHELINE SIZE aligned size is the size in bytes of the buffer to be allocated The actual size allocated will be rounded up by the heap allocator for cache coherency and alignment constraints mflags specifies the memory attributes of the buffer being requested Valid values are ICS CACHED and ICS _UNCACHED 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_heap_base Query ICS heap for virtual base Definition include lt ics h gt ICS VOID ics heap base ICS HEAP heap ICS MEM FLAGS mflags Arguments heap Heap handle mflags Request cached or uncached mapping Returns Associated heap parameter Errors NULL Virtual base address of heap not found Context Callable from task context only Can be called before ICS_cpu_init Description ics heap base returns the virtual
92. S port alloc allocates an ICS port for receiving on the local CPU Ports can either be named or they can be local and anonymous if NULL is passed as the name All named ports are registered with a global name server from which they can be discovered using the function ICS_port_lookup ICS _port_alloc defines a callback function to be invoked in interrupt context whenever a new message arrives at the port and may be NULL ifa process based approach to receiving is wanted ICS_port alloc returns a port handle for use in subsequent functions ICS port_free frees up and closes a previously allocated port including de registering its name from the global name server ICS_msg_send is used to send a message to a port based on a handle obtained from a local allocation or through a lookup of a port name The message data is presented as a virtual address in an argument to the function An mf lags argument allows the caller to control how the data is transferred and how it is presented to the target receiver for example if the data is to be copied inline or if a buffer has been provided which allows the transfer to be done using zero copy techniques There are two approaches to receiving a message from a port process or interrupt based Interrupt based receiving uses the callback function defined at port allocation time which has prototype ICS ERROR ICS PORT CALLBACK ICS PORT port ICS VOID param ICS MSG_DESC rdesc The callback funct
93. S_DBG_PORT Log port actions ICS_DBG_NSRV Log name server actions ICS_DBG_WATCHDOG Log watchdog actions 8182595 Rev 5 137 224 Inter core system ICS API UM1112 138 224 Table 26 ICS debug logging flags continued Debug flag ICS _DBG_HEAP Description Log heap actions ICS_DBG_REGION Log region actions ICS_DBG_LOAD Log load actions ICS _DBG DYN Log dynamic loader actions 8182595 Rev 5 3 UM1112 Inter core system ICS API ics_err_str Definition Arguments Returns Errors Context Description 3 Returns an ICS error string include lt ics h gt const ICS CHAR ics err str ICS ERROR err err An ICS_ERROR error code A pointer to the corresponding ICS error string None Callable from task and interrupt context Can be called before ICS_cpu_init ics err_str returns a pointer to the corresponding ICS error string based on the supplied err code This function is a useful way to display log a text string describing the ICS error code when an error occurs err should be a valid ICS error code as returned by an ICS API function 8182595 Rev 5 139 224 Inter core system ICS API UM1112 ics_heap_alloc Allocate a buffer from an ICS memory heap Definition Arguments Returns Errors Context Description 140 224 include lt ics h gt ICS VOID ics_ heap alloc ICS HEAP heap ICS SIZE size ICS MEM FLAG
94. UG CFLAGS The contents of this variable are placed on the command line for every compiler invocation allowing DEBUG_CFLAGS to be used to defined C pre processor macros the alter the build Table 33 Pre processor macros that enable diagnostic code Pre processor macro Purpose Enable all debug assertions within the ICS tree Also causes the tracing code to be compiled in When used alone this macro does not cause any tracing to be output since each module must have tracing separately enabled ICS _ DEBUG ICS DEBUG FLAGS lt mask gt _ Enable individual ICS subsystem library tracing Enable extra checking and tracing of all memory allocations from ICS_DEBUG_MEM 1 the ICS subsystem Enable all debug assertions within the MME tree Also causes the tracing code to be compiled in When used alone this macro does not cause any tracing to be output since each module must have tracing separately enabled MME DEBUG MME DEBUG FLAGS lt mask gt _ Enable individual MME subsystem library tracing To build an Multicom tree with the maximum possible amount of diagnostic code the following command line could be used make DEBUG CFLAGS DICS DEBUG DICS DEBUG MEM 1 DICS DEBUG FLAGS 1 DMME DEBUG DMME DEBUG FLAGS 1 DEBUG_ CFLAGS does not have to be specified on the make command line it can also be set as an environment variable 8182595 Rev 5 ky UM1112 Advanced build options C 2 3 Whe
95. UM1112 Note 1 9 14 224 Individual test modules can be loaded using cd test insmod src tests ics channel channelll main ko insmod src tests mme api apil0 main ko However the tests which require further executables to be loaded require that all binaries are copied into 1ib firmware on the target file system Because 1ib firmware does not support directory hierarchies each file needs to be renamed to include the CPU name For example on an MB671 we might do cp bin os21 st231 mb671 audio0 ics channel channelll main elf lib firmware channelll main audio0 elf In this example the name of the test module channe1l11_main is appended with the CPU name audioo and the extension e1f used instead of ko The Linux test suite fails if these binaries are not present or have a different filename The Linux 1ib firmware file loading system has a maximum filename length of 32 characters including the terminating 0 Because of the filename length limit of the Linux firmware loader some symbolic links are required in order for the MME test suite to run correctly For example on an MB671 create the following links In s buffercontent10 main audio0 elf lib firmware bc10 main audio0 elf In s buffercontent10 main audiol elf lib firmware bc10 main audiol elf In s buffercontent10 main videoO elf lib firmware bc10_ main videoO elf In s buffercontent10 main videol elf lib firmware bc10_ main videol elf BSP configuratio
96. VER _NOT INITIALIZED MME INVALID HANDLE MME INVALID ARGUMENT MME_COMMAND_ TIMEOUT MME_SYSTEM_INTERRUPT MME ICS ERROR MME_DATA_UNDERFLOW MME_DATA_OVERFLOW MME_TRANSFORMER_TIMEOUT Block waiting for command completion MME _TransformerHandle t Handle Handle of the associated transformer Command identity of the command to wait for Pointer to an MME_Event_t to return associated event type in Timeout period in milliseconds or MME TIMEOUT INFINITE The command was successfully waited for The MME driver has not been initialized The handle does not refer to an existing transformer or the supplied CmdTd is invalid One or more of the supplied arguments are invalid The command did not complete before the Timeout period expired this might be due to the CPU hosting the transformer crashing or failing to respond The wait operation was interrupted An ICS subsystem error occurred A data underflow event occurred A data overflow event occurred The command has been timed out due to MME WaitCommand can be used to block waiting for a command to complete that has been issued with MME_SendCommand and given the MME_CommandEndType_t CmdEnd value of MME_COMMAND END _RETURN_WAKE passed in using MME Command _t On successful completion of MME_WaitCommand MME SUCCESS is returned and the associated event type is updated through Event_p For a normal completion this is set to MME_COMMAND_COMPLETED_EVT Once a MME_Wa
97. _connect ICS _UINT cpuNum ICS UINT flags ICS LONG timeout Arguments cpuNum Logical CPU number flags Various flag bits which affect behavior timeout Connection timeout period Returns ICS SUCCESS Successfully connected to CPU Errors ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS SYSTEM TIMEOUT Connection timed out ICS SYSTEM ERROR A system error occurred Context Callable from task context only Description ICS cpu_connect connects to a logical CPU so that it can be communicated 3 with Normally all logical CPUs are automatically connected during ICS_cpu_init Butin the case of a CPU failure they are disconnected by calling ICS_cpu_disconnect Once the failed CPU has been restarted the programmer should call ICS_cpu_connect to re enable communications with that CPU cpuNumn is the logical CPU number for which the connection is required Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 159 224 Inter core system ICS API UM1112 ICS_cpu_disconnect Disconnect ICS communication from a CPU Definition Arguments Returns Errors Context Description Note 160 224 include lt ics h gt ICS_ERROR ICS_cpu disconnect ICS_UINT cpuNum ICS _UINT flags cpuNum Logical CPU number flags Various flag bits which affect behavior ICS SUCCESS Successfully disconnected from CPU ICS NOT _I
98. a Linux kernel module to call MME_ Init or MME_Term because initialization and de initialization occur automatically when then module is loaded and unloaded 2 11 3 Relocatable library linking Multicom also supports relocatable libraries also known as dynamic modules which can be loaded and unloaded during application runtime Relocatable libraries are only supported on the CPUs that run OS21 For example in order to compile an ST231 compatible ELF module a command similar to the following can be used st200cc mcore st231 mruntime os21 fpic rlib fvisibility protected dyn c o dyn out Note It is recommended that ST200 Micro Toolset R6 4 0 or later is used when building relocatable libraries 3 8182595 Rev 5 33 224 Writing an MME transformer UM1112 3 3 1 34 224 Writing an MME transformer Overview This chapter describes the process of interfacing a transformer to the MME API for use by applications It is assumed that the reader is completely familiar with the MME API described in Chapter 2 Using the MME API on page 15 The function to register transformers MME_RegisterTransformer is introduced in Section 2 3 2 Registering transformers on page 21 This function takes as arguments five function pointers which are called by MME when a transformer specific operation is requested by the application see Table 3 All transformers are therefore required to provide five functions corresponding to the func
99. able As such once the first part of the JPEG is available it is useful to initiate the transform knowing that the remaining part of the image will be provided by the application when or before the input buffer underflows Unlike frame based transformers stream based transformers or the stream based side of a hybrid transformer will not return an error during data underflow or overflow Instead a MME DATA UNDERFLOW EVT or MME NOT ENOUGH MEMORY EVT event is issued and the command suspends its execution waiting for further data Both underflow and overflow are exceptional events and should not occur during normal operation of a streaming transformer They exist only to allow these circumstances to be handled gracefully When underflow or overflow occurs all processing at the same priority is halted on that processor This has the potential to waste significant processor bandwidth particularly in single purpose companion processors Other transformer priorities are not effected See Section 3 4 3 Streaming and hybrid transformers on page 41 In order to prevent these problems the application should normally buffer sufficient input data or output space for this situation to be avoided Where buffering exposes latency problems when changing streams for example in trick modes or during channel change then MME_AbortCommand provides a means to mitigate this When a data buffer has been consumed or filled completely the MME_SEND BUFFER comman
100. ading starting monitoring and recovering from errors in other CPUs in the SoC The intention is that the ICS run time will be loaded onto all the CPUs during system boot and initialization and then used as a building block to provide higher level features and functionality The ICS API reference lists all the functions in the ICS API The purpose of this overview is to introduce the key concepts of ICS and the key functions associated with each concept In some cases the ICS APIs rely on some underlying system libraries available with the tools for compiling programs on the CPUs notably ELF file loading and relocatable library loading libraries ICS API function names begin with ics_ system initialization and loading functions or Tcs_ system initialization communication memory management and support functions The function ICS_cpu_init or ics _cpu_init must be called on the current CPU before any function beginning with ICs_ is called Figure 7 Multicom 4 ICS context ST40 host ST200 audio video r Application a l l Audio Video l driver driver l l Dynamic objects r ICS Static object Static code loader ICS Dynamic code loader Dynamic code loader l Debug logger Debug logger Watchdog Watchdog Inter core communications Inter core communications 3 8182595 Rev 5 UM1112 Overview of the inter core system ICS 5 1 Summary of ICS fa
101. age are printed in teletype font For example void e Non terminal strings of the language that is those built up by rules of the language are printed in italic teletype font For example name e f anon terminal string of the language starts with a non italicized part it is equivalent to the same non terminal string without that non italicized part For example vspace name e Each phrase definition is built up using a double colon and an equals sign to separate the two sides e Alternatives are separated by vertical bars e Optional sequences are enclosed in square brackets and e Items which may be repeated appear in braces and 3 6 224 8182595 Rev 5 UM1112 Preface Mathematical notation A range of values can be shown using square braces and round braces Square braces mean the nearest value is included and round braces mean the nearest value is not included For example 1 3 is the values 1 2 3 1 3 is the values 1 2 Tee 3 is the values 2 3 1 3 is the value 2 only Acknowledgements 3 Linux is a registered trademark of Linus Torvalds Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States and or other countries 8182595 Rev 5 7 1224 Building Multicom UM1112 1 1 8 224 Building Multicom Overview Multicom 4 is supplied as a set of source files a
102. allback Function pointer to handle both command and data callbacks CallbackUserData Anonymous data provided with the callback Those data will be passed as parameters every time the transformer will call its associated CallbackUserData functions TransformerInitParamsSize Size in bytes of the associated parameter array typically obtained using MME _ LENGTH BYTES TransformerInitParams_p Pointer to an allocated parameter array that the contains additional parameters if required transformer specific MME_InitTransformer 3 8182595 Rev 5 UM1112 MME API MME_UINT Type used by MME_Command _t defines numeric value Definition include lt mme h gt typedef unsigned lt qualifier gt int MME UINT Description Unsigned integer type of at least 32 bits On MME implementations that share memory structures directly the size of this type will be identical on all processors An MME implementation that copies structures may define this type differently on each processor to maximize efficiency 3 8182595 Rev 5 109 224 Overview of the inter core system ICS UM1112 5 Note 110 224 Overview of the inter core system ICS ICS in Multicom is a run time system that provides program execution management and communications between all the CPUs on an ST SoC ICS replaces the EMBxX layer in previous versions of Multicom with a simpler approach to communication and with the addition of facilities for lo
103. also MME_Command_t 3 MME_SendCommand 8182595 Rev 5 83 224 MME API UM1112 MME_CommandEndType _ t Definition Description Fields See also 84 224 include lt mme h gt typedef enum Constant used by MME_Command_t defines completion behavior of command MME_COMMAND END RETURN_NO_INFO MME COMMAND END RETURN NOTIFY MME COMMAND END RETURN WAKE MME _CommandEndType t Defines the behavior on the completion of aMME_SendCommand command MME COMMAND END RETURN_NO INFO No event will be generated when the command completes But the MME _CommandStatus_t structure passed when calling MME_SendCommand is filled giving the application the opportunity to retrieve the command status MME COMMAND END RETURN NOTIFY An event will be generated when the command completes by calling the callback function passed when the transformer was instantiated MME COMMAND END RETURN WAKE MME_UINT MME_Command_t MME_SendCommand MME_WaitCommand 8182595 Rev 5 When the command completes no callback is issued Instead the command is signalled to complete any calls of MME_WaitCommand 3 UM1112 MME API MME_Commandld_t Command identifier Definition include lt mme h gt typedef MME UINT MME CommandiId t Description Used to identify a command This identifier is allocated by MME when a call is made to MME_SendCommand 3 8182595 Rev 5 85 224 MME API UM1112 MME_CommandState_t
104. alue MME TUNEABLE BUFFER POOL SIZE before calling MME Init All buffers allocated from the common buffer pool are guaranteed to be accessible by all transformers and both cached and uncached translations can be requested by making use of the Flags argument If the user is intending to manually manage the MME data buffers then the default buffer pool size can be set to a small value However even in this case the common buffer pool will be used for the MME command meta data and hence should be sized accordingly Manually managing data buffers MME permits any memory locations accessible by the host to be used in data buffers and scatter pages Linux User Mode applications are the exception to this see Section 2 5 4 This allows most applications to manage memory for themselves and construct data buffers and scatter pages as required All user managed buffer memory must first be registered with MME by using the MME RegisterMemory function Failure to do this causes the MME_SendCommand operation to fail If cached and uncached translations of this buffer memory are required then memory registration calls with both cached and uncached translations of the memory region must be made Memory can be registered and deregistered using the following functions MME ERROR MME RegisterMemory MME TransformerHandle t Handle void Base MME SIZE Size MME MemoryHandle t Handle p MME _ ERROR MME DeregisterMemory MME MemoryHandle_t Handle
105. ameter array above It is assumed that the transformers header file will be included by the application Send some parameters with a command MME Command_t command sizeof MME _Command_t MME SET GLOBALTRANSFORM PARAMS MME COMMAND END RETURN NOTIFY MME _STExampleTransform_t transformParams MME _STExampleTransform_t transformSubParams Set the individual element to 45 MME PARAM transformParams STExampleTransformNormal 45 Set the array element at index 2 to 70 MME INDEX PARAM transformParams STExampleTransformArray 2 70 Set the sub structure element to 8 MME PARAM transformSubParams STExampleSubNormal 8 Setup the substructure within the parameter structure MME PARAM SUBLIST transformParams STExampleTransformSublist transformSubParams Specify the parameters with the MME Command t structure command Params p amp transformParams command ParamSize MME LENGTH BYTES STExampleTransform MME SendCommand handle amp command 3 8182595 Rev 5 49 224 MME API UM1112 4 50 224 MME API This chapter describes the MME API in terms of its functions constants enums and types Table 6 identifies which functions are supported on Linux user space Table 6 Support on Linux user space Functions supported on Linux user space MME AbortCommand Functions NOT supported on Linux user space MME DebugFlags MME AllocDataBuffer
106. and issue commands to transformers So in practise any CPU in an MME system can act either as a host or a companion or both simultaneously The only exception to this is that a program in Linux user space cannot register transformers Multi hosting can be used to build complex systems where decode and compute are off loaded to one or more of the companions CPUs Here are a couple of example usage scenarios e On a multi ST40 SoC such as the STi7141 both the ST40 CPUs could act as hosts and issue commands to any one of the three ST231 CPUs simultaneously e Onan SoC such as the STi7200 which has four ST231s the Audio decode could be partitioned and off loaded to both Audio CPUs as shown in Figure 3 This can be done transparently to the application running on the ST40 host by nesting transformations For example the host CPU issues an Audio decode transformation command to the Audio codec which is registered on the AudioO CPU this transformer has in turn instantiated a transformer registered on the Audio1 CPU As each command arrives the Audio codec running on AudioO issues transformation commands to Audio to off load some of the compute Once these complete it can then complete the original transformation command from the host 3 8182595 Rev 5 UM1112 Using the MME API Figure 3 Transformer instances multi hosting Host ST40 Video_decode Companion ST231 Audio decode Transformer_name_2 Companion ST231
107. and uncached translations Support for declaring ICS companion firmware on the module load The parameters used for this purpose have the following syntax firmware companion companion companion lt cpu gt lt filename gt Where lt cpu gt can either be the logical CPU number integer or the CPU core name for example audioo or videoo lt filename gt must be an ASCII filename of an ELF file located in lib firmware Support for contiguous allocations from a named BPA2 memory partition The parameter used for this purpose have the following syntax bpa2_ part part name The default for this value is bigphysarea 3 8182595 Rev 5 UM1112 Revision history Revision history Table 34 Document revision history Date Revision Changes Supports the Multicom 4 R4 0 9 6 Minor rewordings not listed Added Note to Section 1 2 Building the library code on page 9 Added Table 6 Support on Linux user space on page 50 Added list of ICS API supported on Linux user space to Chapter 6 Inter core 07 Nov 2013 5 system ICS API on page 125 Updated MME_GetTransformerCapability on page 58 to add MME_NOMIPS error code Added MME_IsTransformerRegistered on page 62 Updated MME_TransformerCapability_t on page 106 to add AdditionalStatus field Supports the Multicom 4 R4 0 6 Minor rewordings not listed Updated Chapter 1 Building Multicom on page 8 throughout to include some details previously
108. annels callback is a pointer to function of type ICS CHANNEL CALLBACK which will be invoked each time a new entry arrives in the FIFO It will be invoked in interrupt context supplying the param and buffer pointer to a FIFO entry If callbacks are not required then these parameters can be set to NULL In this case the FIFO messages can only be retrieved using ICS_channel_recv base is an optional pointer to an area of memory that can be used as the inter CPU FIFO channel As such it must be at least nslots ssize bytes in size and the address must also be ICS_PAGE ALIGNED aligned Supplying a NULL value for this parameter will cause the call to allocate the memory itself nslots is the number of FIFO slots required It must be greater than one and also a power of 2 in size ssize is the size of each FIFO slot in bytes it must be a whole multiple of ICS CACHELINE SIZE Currently no flags bits are defined and this parameter must be set to zero channelp should be a pointer to an ICS CHANNEL object in which the allocated channel handle will be returned on successful completion 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_CHANNEL_CALLBACK Channel callback function Definition include lt ics h gt typedef ICS ERROR ICS CHANNEL CALLBACK ICS CHANNEL channel ICS_ VOID param void buffer Arguments channel Handle of associated channel param Parameter as supplied with the allocation function buffer Channe
109. arameter TeePipes followed by an normal parameter Flange The array nature of TeePipes is reflected in the offset of the subsequent parameter Flange enum MME OFFSET TeePipes MME OFFSET Flange MME OFFSET TeePipes 10 define MME TYPE TeePipes UINT32 usage example assign variable x the value of the fifth element of the parameter TeePipes uint32 x MME_INDEXED_PARAM list TeePipes 5 Parameter arrays as parameters It is quite possible for a parameter array to wholly contain another parameter array to facilitate the mapping of structures within structures into MME parameters In this case the parameter is defined only by its offset since its type is known to be MME_GenericParam t Like array parameters the length of the parameter array is defined by the offset of the subsequent element 8182595 Rev 5 ky UM1112 Writing an MME transformer For example enum MME OFFSET MySublist MME OFFSET NextParameter MME OFFSET MySubList MME LENGTH Sublist i usage example assign variable s to the pointer MySubList an element of the parameter list MME _GENERIC64 s MME PARAM SUBLIST list MySubList Recording the length of a parameter array Once all the offsets for a particular parameter array have been defined the length of the array must be defined in a standard form so that it can be returned by the MME_ LENGTH macro This symbol is derived from the name of the pa
110. ard support package A 3 2 3 Mailbox tables Filename stx7141 st40 estb mbox c define MBOXO ADDR 0xfe211000 define MBOX1 ADDR 0xfe212000 define MBOX2 ADDR Oxfe211800 define MBOX3 ADDR O0xfe212800 ifdef __os21__ include lt os21 st40 sti7141 h gt define VIDEO MBOX IRQ unsigned int amp 0S21_ INTERRUPT MBOXO SH4 IRQ MBOXO SET2 define ECM MBOX IRQ unsigned int amp 0S21 INTERRUPT MBOX2 SH4 IRQ MBOX2 SET2 define AUDIO MBOX IRQ unsigned int amp 0S21_ INTERRUPT MBOX1 SH4 IRQ MBOX1 SET2 define ESTB MBOX _IRQ unsigned int amp 0S 21 INTERRUPT MBOX3 LX DH IRQ MBOX3 SET1 endif ifdef _ KERNEL _ Based on a ILC3 base of 65 offsets in ADCS 8071978 Table 10 define VIDEO MBOX _IRQ define AUDIO MBOX _IRQ 9 MBOXO SET2 11 MBOX1 SET2 65 define ECM MBOX IRQ 65 13 MBOX2 SET2 65 65 define ESTB MBOX IRQ 14 MBOX3 SET1 endif struct bsp_mbox_regs bsp_mailboxes base void MBOXO ADDR Video LX Mailbox MBOX0O 1 interrupt 0 Video owns SET1 flags 0 base void MBOXO ADDR 0x100 Video LX Mailbox MBOX0 2 interrupt VIDEO_MBOX_ IRQ WE own SET2 flags 0 base void MBOX2_ ADDR ST40 ECM Mailbox MBOX2 1 interrupt 0 ECM owns SET1 flags 0 base void MBOX2_ADDR 0x100 ST40 ECM Mailbox MBOX2 2 interrupt ECM MBOX IRQ
111. are used to enable zero copy message passing to be achieved by allowing common regions of physical memory to be mapped by each CPU map is the optional virtual address of the base of the memory region being registered If it is set to NULL then the appropriate mapping will be created on the local CPU The supplied mflags and paddr arguments must be consistent with those of the map Virtual address paddr should be the physical address of the memory region being added It should be aligned to an ICS_PAGE_ SIZE boundary size is the size in bytes of the whole memory region It should be a whole multiple of ICS PAGE SIZE mflags specifies the memory attributes of the region being added Valid values are ICS CACHED and ICS UNCACHED Memory mappings with the corresponding 8182595 Rev 5 ky UM1112 Inter core system ICS API memory attributes will be created on the remote CPUs and also on the local CPU if a NULL map parameter was supplied cpuMask should be a logical CPU bitmask of each CPU which is required to map the new region Passing in ICS_CPU_ALL for this argument will cause it to be added to all CPUs present Note The calling CPU is assumed to be present in this CPU bitmask and not setting the corresponding bit will have no effect regionp is used to return a region handle to the caller This handle should be used in future ICS_region_remove calls 3 8182595 Rev 5 191 224 Inter core system ICS API UM1112
112. ary or Linux kernel in the case of Linux systems to be booted into each of the CPUs and each instantiation is provided with the information needed to set up the ICS system on that CPU so that it can share memory and where appropriate control the other CPUs This information is derived from a BSP which provides SoC specific information and a CPU mapping table A number of BSPs are provided with the ICS and Appendix A ICS board support package on page 201 also describes a template BSP that can be used to create custom BSPs CPU loading and initialization The facilities for loading and starting other CPUs on the SoC are new in this version of Multicom similar facilities were not available in earlier versions of Multicom but are defined now so that the API provides a full self contained set of facilities for multi CPU system development It is not necessary to use the Multicom APIs for this purpose the loading starting and restarting of CPUs can be done by application code directly and or using other libraries as available In the ICS model an SoC consists of a set of CPUs one of which is typically denoted as the master CPU sometimes called the host CPU which has the responsibility of loading and starting the system The other CPUs in the SoC are typically denoted the companion CPUs It is envisaged that the master CPU will be used to load the initial software for the other cores and hence the firmware loading and CPU execution ICS funct
113. ates due to the requirement of minimizing communication between the host and companion All commands that are scheduled on a companion processor appear to the application to be in the MME_ COMMAND EXECUTING state If execution has terminated either by normal completion of processing or due to an error the state changes to one of the final states MME COMMAND COMPLETED or MME _COMMAND_FAILED Callbacks occur whenever execution of a command completes or blocks due to command overflow or underflow conditions which are described in Section 2 10 2 Stream based and hybrid operation on page 31 Executing commands enter the deferred state when a transformer delegates processing to the hardware block The deferred state is a conceptual state which is not observable by the host When a command is deferred subsequent commands are executed by the processor while the original command is executed by an independent hardware accelerator A 8182595 Rev 5 ky UM1112 Using the MME API Note 2 7 1 Note 2 8 3 deferred command can either proceed directly to one of the final states or re enter the MME COMMAND PENDING state and wait for processor time Applications should never repeatedly poll the state of a command as this has the potential to deny other threads the use of the processor Instead of polling the application should utilize callbacks Aborting commands It is possible for the application to request that a command is
114. ations are at the heart of the MME API All the other API calls and transformer commands exist solely to assist with data transformations The command code for data transformations is MME_TRANSFORM Wherever possible data transformations are supplied with both input and output buffers as part of the transform command Most complex transformers also take some transformer specific command parameters Typically this parametric information is purely local affecting only the current transformation although it is quite legitimate for this to affect some global state For example when changing channel in a set top box application a transformer reset might be requested Providing supplementary buffers In some cases it is not possible for a data transformation to be supplied with all the data buffers required for the transformation to complete The reasons for this are outlined in Section 2 10 1 and Section 2 10 2 If a transformation cannot be supplied with all the data buffers initially then it is necessary to supply supplementary buffers to the transformer This is achieved using one or more MME_SEND_BUFFERS commands MME_SEND_BUFFERS commands do not complete that is enter one of the final states at the point the buffers are supplied to the transformer They complete only when the buffers have been consumed by the transformer This allows the application to know whether a buffer contains valid or in use data without having to identify which transfo
115. atter pages dataBuffer gt ScatterPages p scatterPage for i 0 i lt NUM_SCATTER PAGES i dataBuffer gt ScatterPages p i Page_p pageBase dataBuffer gt ScatterPages p i Size newPageSize dataBuffer gt ScatterPages p i BytesUsed newPageSize pageBase newPageSize Now use the data buffer with the scatter pages Free the data buffer when no longer required dataBuffer gt ScatterPages p origPage MME FreeDataBuffer dataBuffer 8182595 Rev 5 25 224 Using the MME API UM1112 2 5 4 2 5 5 26 224 Data buffers in Linux user mode A Linux user application writer should endeavor to use MME_AllocDataBuffer to allocate a data buffer for use by MME_SendCommand If this is not feasible because a data buffer has been allocated in kernel space by another agent for example a video driver the corresponding user space address of this buffer may be used in the Page_p field of a scatter page MME _ScatterPage t MME SendCommand ensures that the physical pages that comprise the buffer e belong to the calling process e are physically contiguous If either of these criteria are not met MME_SendCommand returns MME_INTERNAL ERROR The cacheability of these contiguous pages is determined from the cacheability flag within the Virtual Memory Area VMA in which the pages reside Cache management When a data buffer is held in cached memory MME is forced to make a pessimistic
116. available hardware resource then MME _InitTransformer_t can return an error code Otherwise as a result of this function being called the transformer must e reserve any hardware resources required by the transformer when running e allocate memory to contain state and parametric information of the transformer instance and return the address of this in the context arguments e initialize any relevant state within the context structure e copy any relevant parametric information from the parameter block into the context structure The parameter information must be copied since the transformer can no longer address any part of the parameter block once this initialization function has completed e provide the MME framework with a pointer to context data specific to the transformer instance 3 2 2 Context data 3 The context data is key to managing multiple instances of a transformer and must contain all state relevant to a transformer instance Any temporary working values must be stored in the context data A transformer that can be instantiated multiple times must avoid global variables In fact because the transformer may be instantiated at different priority levels allowing one instance to pre empt another global variables should not be used even for temporary values 8182595 Rev 5 35 224 Writing an MME transformer UM1112 Note 3 2 3 3 3 Note 36 224 It is possible for a single instance transformer to statically allocate
117. block for a specified amount of time waiting for the name to be registered Once the timeout period has expired and no response has arrived from the name server then ICS SYSTEM _TIMEOUT will be returned Duplicate object names are allowed in the nameserver in which case matching lookups are supplied the referenced objects ina round robin order name should be an ASCII 0 terminated string of length not exceeding ICS NSRV_MAX NAME characters not including the 0 8182595 Rev 5 181 224 Inter core system ICS API UM1112 182 224 flags canbe setto ICS BLOCK to cause the function to block until the named object is registered in the name server timeout is the number of milliseconds an ICS BLOCK call should wait for a response Predefined values of timeout can be used ICS _ TIMEOUT _IMMEDIATE return immediately ICS _TIMEOUT_INFINITE never return data should be a non NULL pointer to an area of memory of at least ICS NSRV_MAX DATA bytes in size sizep should be a non NULL pointer to an ICS_SIZE sized object in which the size of the discovered object data will be returned 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_nsrv_remove Remove an object from the name server Definition include lt ics h gt ICS_ERROR ICS nsrv_remove ICS NSRV_HANDLE handle ICS_UINT flags Arguments handle Handle of object to be de registered flags Various flag bits which affect behavior Retur
118. bug channel set to ICS_DBG_ LOG by default 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_debug_flags Set the debug logging flags Definition include lt ics h gt typedef enum ICS DBG ERR 0x0001 ICS DBG INIT 0x0002 ICS DBG CHN 0x0004 ICS DBG MAILBOX 0x0008 ICS DBG MSG 0x0010 ICS DBG ADMIN 0x0020 ICS DBG PORT 0x0040 ICS_DBG_NSRV 0x0100 ICS DBG WATCHDOG 0x0200 ICS DBG STATS 0x0400 ICS DBG HEAP 0x1000 ICS DBG REGION 0x2000 ICS DBG LOAD 0x4000 ICS DBG DYN 0x8000 ICS _DBG FLAGS void ics debug flags ICS UINT flags Arguments flags Bitmask of debugging flags Returns None Errors None Context Callable from task and interrupt context Can be called before IcS_cpu_init Definition ics debug flags sets the debug logging level of the ICS system The ICS 3 debug libraries are built with conditional debugging enabled for each subsystem In order to log the debug messages from a particular subsystem the corresponding bit the debug flags needs to be set by using this function The valid set of debug flag bits are detailed in Table 26 Table 26 ICS debug logging flags Debug flag Description ICS_DBG_ERR Log all error messages ICS_DBG_INIT Log initialization actions ICS_DBG_CHN Log channel actions ICS_DBG_MAILBOX Log mailbox actions ICS_DBG_MSG Log message actions ICD_DBG_ADMIN Log administration actions IC
119. ceiving CPU which can then process it It is the programmer s responsibility to manage the subsequent release of that memory Figure 10 shows example mappings of memory regions for ST40 and ST200 CPUs 8182595 Rev 5 119 224 Overview of the inter core system ICS UM1112 Figure 10 Multicom memory regions ST40 and ST200 CPUs CPU 0 virtual memory Physical memory CPU 1 virtual memory O N Virtual to Physical to f Region 1 hysical virtual Region 1 cached cached Region 1 Region 1 uncached uncached Region 1 Region 2 Region 2 cached cached c Region 2 Region 2 Region 2 uncached uncached Region 3 Region 3 Region 3 cached cached Region 3 Region 3 uncached uncached 120 224 8182595 Rev 5 Kys UM1112 Overview of the inter core system ICS 3 The ARM Cortex A9 CPU architecture does not support cached and uncached mapping of the same physical memory A physical memory region can only be mapped either as cached or as uncached Violating this rule can cause unpredictable system behavior Figure 11 shows example mappings of memory regions between an ARM Cortex A9 CPU and another CPU such as an ST40 or an ST200 CPU Figure 11 Multicom memory regions ARM Cortex A9 core ARM Cortex A9 CPU Physical memory ST40 or ST200 CPU virtual memory v
120. cheduling and re entrancy 0 00 ee 43 3 7 Parameter passing 2 cee ee eee 44 3 7 1 Data representation 0 2000 eee 44 3 7 2 Mapping application data structures into MME parameters 45 3 7 3 Namespace management 00 eee ees 47 3 7 4 AN CXAMPIC od Gencates ee Gea AR ae eek PAG Da e aan ae 48 4 MME API cots pba neesoone 16 Ueto ees es oo ee 6 ae ee 50 4 1 Function definitions 0 0 0c eens 51 4 2 MME constants enums and types 2000000 0c eee 79 5 Overview of the inter core system ICS 0000eeeeeee 110 5 1 Summary of ICS facilities annuau 111 5 2 ICS initialization and system loading 0 eee eee eee 111 5 2 1 ICS configuration and setup auaa uaaa 112 5 2 2 CPU loading and initialization 0 112 5 2 3 ICS initialization and termination 000000 0 ee 114 5 3 Channel based communication 0 000 cece eee 115 5 4 Port based communication 0 00000 cece eee 117 5 5 Memory region management 0 00 eee eee 119 5 6 Name server 0 00000 122 5 7 Dynamic module loading 0 cece ee nae 122 5 8 CPU watchdog support 0 00 tee 123 5 9 Debug logging support sssaaa saaana 124 6 Inter core system ICS API sunnaanannnnnnnnnnnnnnnnnnnnn 125 6 1 ics_ function definitions 0 0 0 0 cece 126 6 2 ICS_ function definition
121. cilities The following is a summary of the main facilities provided by the ICS API e ICS initialization and system loading see Section 5 2 on page 111 ICS provides API calls to allow the application to set up ICS and to facilitate the loading and execution of the initial software in each CPU in the SoC e Channel based communication see Section 5 3 on page 115 The lowest level communication primitive provided by ICS is that of a channel A channel consists of a unidirectional fixed length fixed size FIFO used for communicating between a pair of CPUs e Port based communication see Section 5 4 on page 117 ICS incorporates a port based communication system closely based on the original EMBxX Port model The ICS port API allows ASCII named ports to be registered on each CPU and then messages can be targeted at those ports e Memory region management see Section 5 5 on page 119 Zero copy data passing between the CPUs is facilitated by sharing physically contiguous regions of memory between CPUs To this end ICS provides functions for managing physically contiguous regions of memory and mapping them for all the communicating CPUs e Name server see Section 5 6 on page 122 The ICS Port model is based on named port handles which can be looked up using a central name sever This name service has been exported as a primary API so that programmers can register data objects associated with an ASCII string e Dynamic module loading see Section 5 7 on page
122. clude lt ics h gt const char ics cpu_name ICS _UINT cpuNum cpuNum Logical CPU number being queried BSP CPU name string NULL CPU not found Callable from task and interrupt context Can be called before ICcS_cpu_init ics cpu_name returns the CPU name string associated with the logical CPU number Examples of BSP Registry tables are given in Table 23 on page 128 and Table 24 on page 128 ics opu lookup ics_cpu_type 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_cpu_reset Reset and stop CPU execution Definition include lt ics h gt ICS_ ERROR ics cpu_reset ICS _UINT cpuNum ICS UINT flags Arguments cpuNum Logical CPU number being reset flags Various flag bits which affect behavior Returns ICS SUCCESS CPU reset was issued successfully Errors ICS INVALID ARGUMENT An invalid argument was supplied Context Callable from task and interrupt context Can be called before IcS_cpu_init Description ics cpu_reset resets the logical CPU and stops execution This is an 3 asynchronous operation and how soon the CPU stops executing code is system dependant It is an invalid operation to attempt to do this against the logical calling CPU number cpuNum should be a valid logical CPU number Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 131 224 Inter core system ICS API UM1112 ics_cpu_self Definition Arguments Retu
123. complete e Setup an asynchronous event that will cause the command to complete at some point in the future This is typically achieved by configuring an interrupt handler task pair that will be signaled when the hardware accelerator has completed its work A task will be required because it is not permitted to call any of the MME API functions from an interrupt handler If an MME_SEND BUFFERS command returns MME_SUCCESS it is deferred just as if it had returned MME_ TRANSFORM DEFERRED This is because it is incorrect for a MME SEND BUFFERS command to complete successfully without asynchronous processing by a matching MME_TRANSFORM command In this case there is no need for the transformer to configure an asynchronous event because command execution by the MME already provides this Pipelined transformers A pipelined transformer is a special case of a deferred transformer Pipelined transformers avoid having to setup an asynchronous handler by checking the state of the hardware accelerator from a subsequent transform command This is broadly analogous to the classic fetch decode execute pipeline common in microprocessor architectures 8182595 Rev 5 ky UM1112 Writing an MME transformer The following example shows the management code for a simple two stage pipelined transformer MME ERROR Pipelined _Transform void ctx MME Command_t cmd MME ERROR errl err2 Do the first part of the transform in software errl
124. cpu_init or ics cpu_init However once communication has begun with the target CPU then ICS MSG CONNECT should not be used otherwise large timeouts will occur in the case of a CPU failure 8182595 Rev 5 177 224 Inter core system ICS API UM1112 ICS_msg_test Test an asynchronous message receive event for completion Definition Arguments Returns Errors Context Description Note See also 178 224 include lt ics h gt ICS_ERROR ICS msg test ICS MSG EVENT event ICS BOOL readyp event Message event handle readyp Pointer to a boolean for returning event status ICS SUCCESS Call completed successfully readyp Boolean of event completion state ICS_NOT_INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid event handle was supplied ICS PORT _CLOSED Port has been closed ICS_SYSTEM_ERROR A system error occurred ICS_SYSTEM_TIMEOUT Wait timed out Callable from task context only ICS _ msg _test polls the state of a message event and sets the readyp parameter based on whether the event is ready or not If the event is indicated as being ready then a subsequent call to ICS_msg_ wait will always complete without blocking ICS_msg_test does not free the message event handle event should be a valid message event handle as returned by ICS _msg_ post readyp should be a pointer to an ICS_BOOL object It will
125. ctions Function name Description ics cpu_name Query the BSP Registry for CPU name string ics cpu_type Query the BSP Registry for CPU type string ics cpu_lookup Query the BSP Registry for CPU logical number ics cpu_self Query the CPU Logical number ics _cpu_mask Query the logical CPU bitmask These functions query the CPU database set up from the BSP The first two return the name string and type string respectively for a specified CPU ics cpu lookup returns the logical number given a CPU name ics cpu_self returns the CPU logical number of the CPU on which it is executing ics_cpu_mask returns the bitmask defining the set of CPUs on the SoC on which ICS has been specified to run The ICS functions for CPU loading and starting are given in Table 10 and Table 77 Table 10 Program loading functions Function name Description ics load_elf file Load and unpack an ELF file ics load_elf image Unpack an ELF memory image ics load_elf fileandics load _elf image load an ELF file to memory either from a file stored in a local file system or from an ELF file image stored in memory The ELF start entry address is returned to the caller in the entryAddrp argument Table 11 CPU control functions Function name Description ics cpu_reset Reset and stop CPU execution ics cpu_start Start execution of a CPU These functions reset and start code running on the CPU specified The CPU number
126. d The MME can generate events when a command completes or fails Event notification may be optionally enabled by the application programmer when a command is submitted Events are delivered to the application by using callbacks Callbacks A callback function and application specific callback data is associated with a transformer when a transformer is instantiated When a command is sent to a transformer the application can choose whether or not it will be notified of any events associated with the command by the associated callback Due time The due time is used by the MME implementation to determine in what order to process commands The command queue for each transformer is maintained in due time order and when a command is dispatched all the queues are examined and the one with the lowest due time is selected for execution The due time is only relevant to MME_SET_GLOBAL TRANSFORM PARAMS and MME TRANSFORM MME SEND BUFFERS commands are executed in strict FIFO order and can pre empt currently running commands See Section 2 8 Fault detection and recovery on page 29 Neither the MME host nor the companion is aware of the current system time This leaves the choice of what time unit to use entirely at the application designers discretion In most cases using the host processor s system clock is recommended Although the MME implementation does not know the unit of time it does know that as time progresses the due time will eventuall
127. d completes If an input data buffer is only partially consumed the command will not complete instead it remains pending until the next MME_TRANSFORM command consumes it Whether a partially filled output data buffer completes before it is full is transformer dependant If the output consists of variable length frames it is normal to complete a partially filled frame and move on to the next one Where the output does not contain frame markers the buffer will not complete until it is completely filled Linking and loading This section describes linking and loading issues for different operating systems 0S21 On 0821 the main application must link against both the ICS and MME libraries Assuming the correct library search path is defined this should be achieved by adding the following to the link command line lmme lics lics_bsp Linux The MME API can be used on a host processor running Linux in either kernel mode user mode or both concurrently There is a single kernel module that must be loaded and a single library that must be linked with a user application 8182595 Rev 5 ky UM1112 Using the MME API However the MME kernel module must be loaded after the ICS kernel module is loaded Also the user application must be linked against the MME user library Assuming the correct library search path is defined this should be achieved by adding the following to the link command line 1mme It is not valid for
128. d is issued to the MME 2 The FlagsOut field is set by the companion transformer before notifying the host that the transform is complete 8182595 Rev 5 ky UM1112 Using the MME API 2 6 2 7 3 Application and transformer specific data MME provides a mechanism for passing application specific or transformer data to and from the transformer When such data is to be passed it is specified by an address of type MME _GenericParams_t at which the data starts and a length in bytes A mechanism for managing the portability of such data is described in Section 3 7 Parameter passing on page 44 Issuing commands Commands are issued using the following function MME ERROR MME SendCommand MME TransformerHandle t Handle MME Command _t CmdInfo_p MME _SendCommand is asynchronous it returns before the command has completed processing For this reason it is possible to examine the state of the command before it has completed The application must fill in several fields of the MME _Command_t structure e StructSize see Section 2 1 7 Structure size on page 20 e CmdCode with the command to perform see Section 2 4 Managing transformer lifetimes on page 22 e CmdEnd to specify whether events such as a command completion cause the callback function to be called e Due time see Section 2 1 5 Due time on page 18 zero for all commands ensures FIFO processing of commands e NumberInputBuffers the number of inpu
129. d when in the MME_COMMAND PENDING state that is before being processed However depending on their implementation some transformers may also accept to abort command during their processing MME_COMMAND EXECUTING state When a command has been aborted the Error field of the MME _CommandStatus _t is setto MME COMMAND ABORTED The callback function on the host is called when the command is successfully aborted Comments Call type non blocking function call the operation completes when the callback function has been called 3 8182595 Rev 5 51 224 MME API UM1112 MME_AllocDataBuffer Definition Arguments Returns Description Comments See also 52 224 include lt mme h gt Allocate MME data buffer MME ERROR MME AllocDataBuffer MME TransformerHandle t Handle MME UINT Size MME AllocationFlags t Flags MME DataBuffer t DataBuffer p Handle Handle of the targeted transformer Size Number of bytes to allocate Flags Specify special requirements of the memory DataBuffer p MME SUCCESS MME DRIVER NOT INITIALIZED MME NOMEM MME INVALID HANDLE MME INVALID ARGUMENT Allocate a new MME data buffer allocated see MME_AllocationFlags_t on page 80 Pointer to a pointer to an allocated data buffer structure to be populated The operation completed correctly The MME driver has not been initialized The memory required to complete this command is not available
130. display log a text string describing the MME error code when an error occurs err should be a valid MME error code as returned by an MME API function 3 8182595 Rev 5 UM1112 MME API MME_FreeDataBuffer Release MME data buffer Definition include lt mme h gt MME ERROR MME FreeDataBuffer MME DataBuffer t DataBuffer p Arguments DataBuffer_p Pointer to an allocated data buffer structure to be freed Returns MME SUCCESS The operation completed correctly MME DRIVER_NOT_INITIALIZED The MME driver has not been initialized MME INVALID ARGUMENT DataBuffer pis invalid Description Release memory previously allocated with MME_AllocDataBuffer This command releases memory previously allocated with MME AllocDataBuffer The behavior is undefined if the memory was not previously allocated by the MME API or if pointers within the structure have been modified Comments Call type blocking function call See also MME_AllocDataBuffer 3 8182595 Rev 5 57 224 MME API UM1112 MME_GetTransformerCapability Return details of transformer capability Definition Arguments Returns Description Comments See also 58 224 include lt mme h gt MME ERROR MME GetTransformerCapability const char TransformerName MME TransformerCapability_ t TransformerCapability_p TransformerName Name of the transformer whose capability is to be queried TransformerCapability p Pointer to an allocated MME_Tra
131. e Errors ICS NAME NOT FOUND Filename not found ICS INVALID ARGUMENT An invalid argument or ELF file was supplied ICS NOT CONNECTED Target CPU is not connected ICS _ENOMEM Failed memory resource allocation ICS_SYSTEM_ERROR A system error occurred ICS SYSTEM TIMEOUT A communications operation timed out Context Callable from task context only Description IcS dyn _load_file is used to load dynamic ELF module files relocatable 3 libraries on the calling CPU and relocate them so that they can be executed on the target CPU On successful completion a dynamic module handle is returned to the caller using the handlep argument The ICS dynamic module system is layered on top of the rl library provided by the ST Micro Toolset Much more detail can be found in the relevant Toolset manuals cpuNun is the logical target CPU of where the dynamic module should be loaded fname should be a local OS filename from where the ELF dynamic module image can be obtained Currently no flags bits are defined and this parameter must be set to zero parent is the ICS_DYN handle of the parent module of the one being loaded If no parent exists then it can be supplied as a zero handle If a non zero parent handle is supplied then the new module will be linked against that module in the target CPU providing symbol inheritance from the parent module 8182595 Rev 5 165 224 Inter core system ICS API UM1112 handlep should be a non NULL po
132. e MME_ TYPE FooBar Macros are used to access the value of an entry in the MME array Individual parameters An individual parameter is a single typed element of the MME parameter array It is defined by an offset into the parameter array together with the type information for that parameter To define a parameter FooBar a constant MME_OFFSET_FooBar is required to describe the offset into the parameter array at which FooBar will be found Similarly a macro MME TYPE FooBar is required to describe the type of the parameter 3 8182595 Rev 5 45 224 Writing an MME transformer UM1112 Note 46 224 MME OFFSET FooBar can be a preprocessor macro though normally because is it merely an integer it is an enumerated constant MME TYPE FooBar must be a preprocessor macro because it contains a sequence of C tokens For example the following would define a unsigned character parameter FooBar at offset one enum MME OFFSET SomeValueAtOffsetZero MME OFFSET FooBar define MME TYPE FooBar unsigned char usage example assign variable c the value of the parameter FooBar unsigned char c MME PARAM list FooBar Array parameters An array parameter is defined in the same way as a individual parameter but is immediately followed by unused locations within the array This allows the array parameter and an index to be used to extract numbered elements Shown below is a ten element array p
133. e SoC specific information such as Mailbox addresses and reset registers in order for ICS to function It also contains the CPU mapping table that is used to map CPU names onto their logical CPU numbers Currently ICS is supplied with BSPs for a limited set of SoCs see the Release notes for further details However it is fairly simple to create a BSP for other SoCs The BSP code can be found in source src bsp Taking the STi7200 as an example we have stx7200 cores c stx7200 st40 mbox c stx7200 st40 name c stx7200 st40 reset c stx7200 st40 sti7200reg h stx7200 st231 audio0 mbox c stx7200 st231 audio0 name c stx7200 st231 audiol mbox c stx7200 st231 audiol name c stx7200 st231 video0 mbox c stx7200 st231 video0 name c stx7200 st231 videol1 mbox c stx7200 st231 videol name c The format and content of these BSP files is straight forward and the supplied BSPs can be used as a template for creating new ones The SoC specific header file sti 7200reg hcan be copied directly from the ST40 Micro Toolset example directory In order for the OS21 BSP to be built by Multicom then the new SoC and core names must be added to the relevant makefiles in the BSP directory for example makebspst40 inc makebspst231 inc For the Linux kernel module build the new BSP files need to be added to source src ics Makefile 3 8182595 Rev 5 201 224 ICS board support package UM1112 A 1 1 Note A 2 Note A 2 1 Note
134. e does not refer to an existing transformer MME COMMAND STILL EXECUTING A command is still executing on the transformer instance Description Terminate an instance of a transformer and free any resources that the instance uses Comments Call type blocking function call 104 224 3 8182595 Rev 5 UM1112 MME API MME_Time_t Type used by MME_Command_t describes time Definition include lt mme h gt typedef MME UINT MME Time_t Description Describe the time in the MME environment See also MME_Command_t 3 8182595 Rev 5 105 224 MME API UM1112 MME_TransformerCapability_t Definition include lt mme h gt typedef struct MME UINTStructSi ze MME UINTVersion MM MM M M M Ei md iw M M ti 4 zal Q Describe transformer capabilities _DataFormat_tInputType ataFormat_tOutputType JINTTransformerInfoSize enericParams tTransformerInfo_ p ME UNITAdditionalStatus MME TransformerCapability t Description Describe the capabilities of a particular transformer Note On multi processor systems the contents of TransformerInfo_p will only be copied in one direction companion to host For this reason all transformers must treat the data pointed to as uninitialized Fields StructSize Size of the structure in bytes Version Version of the transformer InputType Supported input type OutputType Supported output types TransformerInfoSize Size in bytes o
135. e each CPU to be reset By setting an array entry value member to 0 the reset logic applies mask followed by mask to the register Normally these BSP declarations are only supplied in the ST40 sh4 BSPs as they are usually responsible for the reset and loading of the other CPU cores These tables and the associated macro header file are normally copied directly from the ST40 Micro Toolset examples directory CPU core name extern const char bsp_cpu_name This is a CPU core declaration and is usually found in the name c BSP file for each CPU core It should be set to the ASCII CPU core name of the corresponding CPU and must match one of the CPU names found in the bsp_cpus table 8182595 Rev 5 205 224 ICS board support package UM1112 A 3 Example BSP template The following example BSP template is for the MB628 STx7141 based platform SoC Note Only the templates for the estb and audio CPUs are included A 3 1 CPU table Filename stx7141 cores c struct bsp _cpu_info bsp_cpus unsigned int bsp_cpu count sizeof bsp_cpus sizeof bsp_cpus 0 name estb eSTB type st40 num 0 MASTER flags 0 name ecm eCM type st40 num 3 flags 0 name audio audio type st231 num 2 flags 0 name video video Cype st231 num 1 flags 0 i 206 224 8182595 Rev 5 3 UM1112 ICS bo
136. e from task context only ICS _msg_send sends a message to the target port handle This port handle can either be a local port as created with ICS port _alloc ora remote port as discovered with ICS port lookup Messages are always delivered to the target port in the same order they were sent On successful return it is guaranteed that the message will be delivered to the target port The message data should be presented as a virtual address in the buffer argument with its size in bytes being specified by the size parameter The mflags parameter allows the caller to control how the data is transferred and how it is presented to the target receiver Setting mflags to ICS_INLINE causes the data to be copied on send into a system buffer area and subsequently copied to the target receiver as part of the ICS _MSG DESC descriptor Such inline message data cannot exceed ICS _MSG_INLINE_DATA bytes in size 8182595 Rev 5 ky UM1112 Inter core system ICS API Note 3 Setting the mf lags parameters to either ICS_CACHED or ICS_UNCACHED will cause the data to be transferred using zero copy techniques where the buffer address must have come from a memory region which has been previously registered with ICS region_add In this case the target receiver will be presented with the appropriate virtual address mapping of that physical memory buffer that is cached or uncached Setting the flags parameters to ICS PHYSICAL will cause
137. e input frames because the device performing the demultiplex can readily identify end of frame markers If a frame based transformer is not supplied with sufficient buffers it does not block instead it moves to the MME COMMAND FAILED state and sets the appropriate error code in the command status structure When a frame based transformer completes it issues a MME_ COMMAND COMPLETED EVT event and the application receives a callback Stream based and hybrid operation Unfortunately there are number of reasons why it may not be possible for a transformer to be wholly frame based e transformations create an unknown quantity of output e transformations consume an unknown quantity of input e transformations are required to start before all available buffers are ready The first situation is common in variable or average rate encoders From a given input it is computationally unfeasible to estimate how much output will be created 8182595 Rev 5 31 224 Using the MME API UM1112 Note 2 11 2 11 1 2 11 2 32 224 The second situation occurs when a stream format makes it difficult to identify end of frame markers or simply when a stream is not divided into frames The final situation is comparatively rare One example is that of decoding a large JPEG image stored on slow media such as disk It is desirable that the time between opening and displaying the image is minimized by starting to decode data as it becomes avail
138. e passing inline and zero copy message passing For zero copy message passing the memory buffers must be in memory regions that have been pre registered with the ICS system see Section 5 5 Memory region management on page 119 Ports can be either anonymous or named Named ports are registered with a global name server Ports provide a many to one communication model Multiple processes potentially on different CPUs can send to a port Ports implement a FIFO queue of messages between senders and receiver Table 16 Port and message functions in ICS Function name Description ICS port_alloc Allocate an ICS port ICS port_cpu Return the logical CPU number associated with the port ICS port_free Free and close an ICS port ICS _port_lookup Look up an ICS port handle ICS _msg_send Send a message buffer to an ICS port ICS _msg_recv Blocking call to receive a message on an ICS port ICS_msg_post Post an asynchronous receive on an ICS port ICS _msg_cancel Cancel an asynchronous port receive 8182595 Rev 5 117 224 Overview of the inter core system ICS UM1112 Note 118 224 Table 16 Port and message functions in ICS continued Function name Description ICS _msg_test Test an asynchronous port receive event ICS _msg_wait Block and wait for an asynchronous port receive event IC
139. eapBase can be supplied by the caller if a physically contiguous memory region has already been allocated otherwise NULL should be supplied If a memory region address is supplied then it must be ICS_PAGE_ SIZE aligned heapSize is the size of the heap to be created in bytes This value must be a whole multiple of ICS PAGE SIZE Currently no flags bits are defined and this parameter must be set to zero heapp is a pointer to an ICS_ HEAP descriptor in which the allocated heap handle is returned 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_heap_destroy Destroy an ICS heap Definition include lt ics h gt ICS_ ERROR ics heap destroy ICS HEAP heap ICS_UINT flags Arguments heap Heap handle flags Various flag bits which affect behavior Returns ICS SUCCESS Successfully destroyed heap Errors ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid handle was supplied ICS SYSTEM ERROR A system error occurred Context Callable from task context only Can be called before ICS_cpu_init Description ics heap destroy should be called to destroy a heap previously created with ics heap create It will release all resources associated with the heap All allocated buffers must have been returned to the heap before it is destroyed heap should be a valid heap handle Currently no flags bits are defined and this parameter must be set to zero 3 8182595 Rev 5 143 22
140. efined in the channel alloc call and a pointer to the buffer sent Normally the handler will copy and consume the buffer and then call IcS_channel_release If the handler is unable to consume the buffer it will return ICS_FULL and the FIFO will be blocked until the function ICS_channel_unblock is called ICS channel _recv blocks on a receive channel until a new buffer arrives at which point it returns with a pointer to the new buffer Once the application has processed the buffer it should call ICS_channel_ release with the buffer pointer 3 8182595 Rev 5 UM1112 Overview of the inter core system ICS 5 4 3 Port based communication ICS incorporates a port based communication system similar to the EMBX port model provided in previous versions of Multicom see Figure 9 The ICS port API allows named ports to be registered on each CPU and then messages can be sent to those ports The exact location of the target port is not required to be known to the sender and hence ports allow services to be abstracted away from their CPU location APIs are provided for sending messages on ports and for process and interrupt based handling of message reception Figure 9 ICS port model CPU 0 CPU 1 Inter CPU channels Message queue Message queue Port ee Port Name Name3 Nn messages gt 5 Message descriptor Port Name4 Port D an Name2 Named Ports can provide copy based short messag
141. ength MME LENGTH MPGVGlobal MME _PARAM params MPGVGlobal_horizontal_size value hsv MME _PARAM params MPGVGlobal_vertical_ size value vsv for i 0 i lt 64 i MME _INDEXED_PARAM params MPGVGlobal_intra_quantiser_matrix i igm il or to declare parameters statically MPGV_GlobalParams t params 10 10 Lj 2p By Ar Bp Gy Ty By 9 LO Aly L2 13 14 L5 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 S1 52 53 54 55 56 57 58 59 60 61 62 63 y 212 224 8182595 Rev 5 ky UM1112 MME supplement See also MME_AllocationFlags_t MME_SendCommand MME_PARAM MME_INDEXED_PARAM ky 8182595 Rev 5 213 224 MME supplement UM1112 Definition Description Fields 214 224 MPGV_DecodeParams_t enum MPGVIdx E Ll MME LENGTH MPGV MME OFFSET MPGV_ picture type MME OFFSET MPGV_ full pel _forward_vector MME OFFSET MPGV_forward_f code MME OFFSET MPGV_ full pel backward vector MME _ OFFSET MPGV_backward_f code MME OFFSET MPGV_forward_horizontal MME OFFSET MPGV_ forward vertical define MME TYPE MPGV_ picture type define MME TYPE MPGV_ full pel forward vector define MME TYPE MPGV_ forward _f code define MME TYPE MPGV_ full pel _backward_vector define MME TYPE MPGV_backward_f code define MME TYPE MPGV_forward_horizontal
142. ently no flags bits are defined and this parameter must be set to zero schannelp should be a valid pointer to an ICS CHANNEL SEND object 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_channel_recv Blocking call to receive a buffer from an ICS channel Definition include lt ics h gt ICS ERROR ICS channel _ recv ICS CHANNEL channel ICS_VOID bufferp ICS LONG timeout Arguments channel Channel handle bufferp Pointer to a buffer pointer timeout Time in milliseconds to block waiting for a buffer Returns ICS SUCCESS Successfully received a buffer bufferp Buffer pointer returned Errors ICS_NOT_INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid channel handle was supplied ICS _ENOMEM Failed memory resource allocation ICS_SYSTEM_ERROR A system error occurred ICS SYSTEM TIMEOUT Received timed out Context Callable from task context only Description ICS channel _recv blocks on the supplied channel handle awaiting a new FIFO 3 entry arrival The channel handle must be a valid local channel as created with ICS_channel_alloc buf ferp should be a pointer to a unique ICS_VOID pointer used to return the address of the FIFO buffer timeout is the amount of time in milliseconds to block before aborting and returning ICS_SYSTEM TIMEOUT On successful completion the supplied buf ferp pointer will have been updated with the new FIFO entry
143. erver In this case the function will block for the number of milliseconds specified in the timeout parameter Predefined values of timeout can be used ICS TIMEOUT IMMEDIATE return immediately ICS _TIMEOUT_INFINITE never return portp should be a pointer to an ICS_ PORT object in which the discovered port handle will be returned on successful completion 8182595 Rev 5 189 224 Inter core system ICS API UM1112 ICS_region_add Add a region to the local and remote CPU region tables Definition Arguments Returns Errors Context Description 190 224 include lt ics h gt ICS ERROR ICS region_add ICS VOID map ICS OFFSET paddr ICS SIZE size ICS MEM FLAGS mflags ICS _ULONG cpuMask ICS REGION regionp map Virtual address of region base paddr Physical address of region base size Size of the region in bytes mflags Memory region attributes cpuMask Bitmask of logical CPUs regionp Region handle pointer ICS SUCCESS Successfully added region regionp Region handle allocated ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Callable from task context only ICS region_add maps a memory region in both the local CPU and all the remote CPUs as indicated by cpuMask These regions
144. eturned by ICS_channel_open buffer should be a valid virtual address of a data buffer size should be the size of the data buffer in bytes It cannot exceed the size of the channel FIFO slots Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 157 224 Inter core system ICS API UM1112 ICS_channel_unblock Unblock blocked ICS channel Definition Arguments Returns Errors Context Description 158 224 include lt ics h gt ICS_ERROR ICS channel unblock ICS CHANNEL channel channel Channel handle ICS SUCCESS Successfully unblocked the channel ICS NOT _INITIALISED ICS not initialized ICS HANDLE INVALID An invalid channel handle was supplied ICS SYSTEM ERROR A system error occurred Callable from task and interrupt context ICS_ channel unblock should be called to unblock a channel that became blocked due to a channel callback function returning ICS_FULL In this case a buffer would have been left at the head of the FIFO blocking all further communications on that channel Until this function is called no further callback events will be generated on the blocked channel Calling this function with the channel handle of a channel that is not blocked will have no effect 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_cpu_connect Connect to a CPU allowing ICS communication Definition include lt ics h gt ICS_ERROR ICS cpu
145. f the associated parameter array typically obtained using MME _ LENGTH BYTES TransformeriInfo p Pointer to an allocated parameter array where the transformer may store specific capabilities of the transformer transformer specific AdditionalStatus Status about low resource The transformer may set additional status as MME_NOMIPS or MME_NOMEM See also MME_GetTransformerCapability 106 224 8182595 Rev 5 3 UM1112 MME API MME_TransformerHandle_t Transformer handle Definition include lt mme h gt typedef MME UINT MME TransformerHandle t Description Handle returned by MME_InitTransformer Used to identify the transformer for later function calls The value of zero is invalid See also MME _InitTransformer 3 8182595 Rev 5 107 224 MME API UM1112 MME_TransformerlinitParams_t Parameters used to initialize transformer Definition Description Fields See also 108 224 include lt mme h gt typedef struct MME UINT StructSize MME Priority _t Priority MME GenericCallback_t Callback void CallbackUserData MME UINT TransformerInitParamsSize MME GenericParams t TransformerInitParams_p MME _TransformerInitParams t Parameters to use to initialize a transformer The Callback and CallbackUserData fields of the MME TransformerInitParams_t structure are not valid for the transformer StructSize Size of the structure in bytes Priority The transform queue priority C
146. file linux make ARCH arm CROSS COMPILE armv7 linux f Makefile linux Building the test code Having built the source tree the tests can now be built For example to build for the MB671 STi7200 under OS21 issue the following commands cd test make f Makefile st40 PLATFORM mb671 make f Makefile st200 PLATFORM mb671_ audio0d make f Makefile st200 PLATFORM mb671_ videoo make f Makefile st200 PLATFORM mb671_ audiol make f Makefile st200 PLATFORM mb671 videol The OS21 test build support is only provided for some platforms see the Release Notes for details When building the companion tests be careful to ensure that the static code load addresses and memory sizes are arranged so that the memory areas of any two CPU cores do not overlap This is particularly important when running Linux on the ST40 host as its default load address often clashes with that of the ST200 companions To this end the test suite build allows the user to specify an alternative ST200 compiler target directory mtargetdir using the ST200_TARGETDIR make environment variable Set this environment variable to a directory containing ST200 compiler configuration files that correctly define the static code addresses for each CPU To build the kernel test modules for Linux for the MB671 STi7200 issue the following commands adjusting the kernel paths as necessary for the desired target kernel export KERNELDIR usr src linux sh4 2 6 23 17_stm23 0122 export
147. fore the command completes The MME SET GLOBAL TRANSFORM PARAMS command is used to update parameters that affect all subsequent transforms Such command typically have very short execution times since they need only alter a few parts of the context structure prior to returning The MME_SEND_ BUFFERS command partners with the MME_TRANSFORM command to supply data buffers to a streaming transformer This command is discussed in detail in Section 3 4 3 Streaming and hybrid transformers on page 41 3 4 1 Communicating with the application 3 For simple transformers all communication with the application is managed automatically When a command completes its processing and returns an error code by its processing function MME automatically notifies the application that the command has finished processing When a transformer needs to initiate communication with the application the following function is used MME ERROR MME NotifyHost MME Event _t event MME Command_t commandInfo MME ERROR errorCode 8182595 Rev 5 39 224 Writing an MME transformer UM1112 Note 3 4 2 Note 40 224 The circumstances when this function is required are identified by the event type e MME COMMAND COMPLETED _EVT used to mark a deferred command see Section 3 4 2 Deferred commands on page 40 as completed e MME DATA UNDERFLOW EVT and MME NOT ENOUGH MEMORY_EVT used by streaming transformers see Section Underflow and insufficient memo
148. former It is called as a result of a host call to MME InitTransformer The Callback and CallbackUserData fields of the MME TransformerInitParams_t structure are not valid for the transformer Comments Call type blocking function call See also MME_InitTransformer 98 224 8182595 Rev 5 ky UM1112 MME API MME_MAX_TRANSFORMER_NAME Defines maximum length of a transformer name Definition include lt mme h gt define MME MAX TRANSFORMER NAME lt const unsigned int gt Description The maximum length in bytes of a transformer name This constant defines the maximum length of the transformer name that may be passed to MME_InitTransformer andMME RegisterTransformer See also MME_InitTransformer MME_RegisterTransformer 3 8182595 Rev 5 99 224 MME API UM1112 MME_MemoryHandle t Memory registration handle Definition include lt mme h gt typedef MME _UINT MME MemoryHandle t Description Handle returned by MME RegisterMemory Used to identify the memory registration for later function calls The value of zero is invalid See also MME_RegisterMemory MME_DeregisterMemory 3 100 224 8182595 Rev 5 UM1112 MME API MME_Priority_t Definition Description See also 3 include lt mme h gt typedef enum MME PRIORITY HIGHEST MME PRIORITY ABOVE NORMAL MME _ PRIORITY NORMAL MME _ PRIORITY BELOW NORMAL MME _ PRIORITY LOWEST MME_Priority t The priority at w
149. gistration on a companion this function should be called iteratively until MME_ SUCCESS is returned MME Init must be called prior to the MME_InitTransformer function Comments Call type blocking function call See also MME_Init 3 MME_ Term Transformer 8182595 Rev 5 61 224 MME API UM1112 MME_IsTransformerRegistered Check whether a transformer is registered Definition Arguments Returns Description Comments See also 62 224 include lt mme h gt MME ERROR MME IsTransformerRegistered const char Name Name Name of the transformer This is checked to determined whether it is registered MME SUCCESS A transformer with the specified name is registered MME UNKNOWN TRANSFORMER No transformer of the specified name exists MME DRIVER_NOT_INITIALIZED The MME driver has not been initialized MME INVALID ARGUMENT Name pointer name is invalid Checks that a specified transformer is registered The name argument must not be longer than MME_MAX TRANSFORMER_NAME bytes The error code MME_UNKNOWN_ARGUMENT will be returned if the name is too long Call type blocking function call MME_RegisterTransformer MME_DeregisterTransformer 3 8182595 Rev 5 UM1112 MME API MME_LENGTH Return the length of a parameter array Definition Arguments Returns Description See also 3 include lt mme h gt define MME_LENGTH name name Name of the parameter array T
150. gsIn MME _UINT FlagsOut MME ScatterPage t Description Describe a scatter page that is a linear memory range within a data buffer BytesUsed is meaningless until the transformation completes It is filled by the transformer with the number of bytes it wrote into this page while processing data The FlagsIn field and FlagsOut fields are used to pass additional information about the scatter page The FlagsIn field is used to pass state from the host to the transformer The FlagsOut field is used to pass state from the transformer to the host Both fields are divided into two regions the MME region and the application region The MME region is the upper 8 bits unused bits in the MME region are reserved and must be set to zero The remaining 24 bits are available to the application and transformer see Table 2 MME_ScatterPage_t Flagsin and FlagsOut on page 26 Fields Page p Address of the memory space Size Size of the page in bytes BytesUsed Number of bytes used in this page FlagsIn Combination of generic and transformer specific flags FlagsOut Combination of generic and transformer specific flags See also MME_DataBuffer_t 3 8182595 Rev 5 103 224 MME API UM1112 MME_TermTransformer_t Terminate a transformer instance Definition include lt mme h gt MME ERROR MME TermTransformer_t void context Arguments context Context of the transformer Returns MME SUCCESS Success MME _ INVALID HANDLE The handl
151. guments event The event that should be passed to the host callback See MME _NotifyHost description commandInfo The MME _Command_t passed into the transformer function MME ProcessCommand_t errorCode The error state of the command Returns MME SUCCESS The host has been notified MME INVALID ARGUMENT An argument is invalid MME DRIVER NOT INITIALIZED The MME driver has not been initialized Description Informs the host that the transformer has generated an event This function must not be called from an interrupt handler The event argument can be one of the events listed in MME_Event_t on page 94 This call will cause the application supplied callback function on the host to be called with the its event parameter set to the value of event Comments Call type non blocking function call 3 8182595 Rev 5 67 224 MME API UM1112 MME_PARAM Extract named parameter Definition include lt mme h gt define MME PARAM params name Arguments params Pointer to a parameter array of type MME GenericParams t name Name of the parameter to be extracted from the array Returns An 1value an object that can be assigned to whose type is selected by the named parameter Description Extract a named parameter from a parameter array This macros uses other special purpose macros or named constants to process the name For example the following macros define a parameter name called ThisIsAGlobalName enum MME OFFSET ThisIsAGlobalName 2
152. h codec or media transformation it can perform see Section 2 3 2 Registering transformers on page 21 The host will then use the symbolic name of each of the transformers it requires to lookup and instantiate them see Figure 2 Figure 2 Transformer instances single host Host ST40 Companion ST231 Video_decode Transformer_name_1 Audio_decode Transformer_name_2 Companion ST231 Transformer_name_3 Transformer_name_4 3 8182595 Rev 5 15 224 Using the MME API UM1112 16 224 When a transformer is instantiated the abstract transformer is combined with parametric and state information it is then capable of processing data This is called a transformer instance Typically transformers that rely on hardware accelerators can only have one instance at a single point in time due to there only being one accelerator However for software transformers it is unusual for anything other than available memory to limit the number of instances of a particular transformer Multi hosting support This version of Multicom also supports a usage model known as Multi hosting Traditionally in an MME system there would have been one host CPU for example an ST40 and multiple companion CPUs for example ST231s however newer SoCs now incorporate multiple ST40 CPUs Multi hosting means that any CPU in the MME system can act as a host and hence instantiate
153. he definition of MME_Command_t and is therefore not prefixed by a structure size Fields AdditionalInfoSize and AdditionalInfo_p are filled by the caller before calling the MME_SendCommand function The data pointed to by AdditionalInfo_p is transported bidirectionally that is it is sent from the host to the companion when the command is submitted and back from the companion to the host when the command completes Field CmdTd is filled by the MME_SendCommand function Fields ProcessedTime and Error are filled by MME itself These fields are relevant only when the command has been processed that is when the field State has turned to the MME_COMMAND_ COMPLETED or MME _ COMMAND FAILED value This structure is owned by the transformer once passed into the MME ProcessCommand_t transformer entry point and the State field may be modified by the transformer to reflect that a transform has been deferred See Section 3 4 2 Deferred commands on page 40 CmdId Unique identifier of the command the structure is related to This field is filled by the MME_SendCommand function State State of the command ProcessedTime Time spent processing the command Error Command status as a result of processing AdditionalInfoSize Size in bytes of the associated parameter array typically obtained using MME_LENGTH_BYTES AdditionalInfo_p Pointer to an allocated parameter array where the MME can store additional info related to the performed transformati
154. he length of the named parameter array Find the length of a named parameter array This macro uses other special purpose macros to process the name For example the following macros define a parameter name called ThisIsAGlobalName define MME PARAMS LENGTH ThreeParameters 3 The macro should be used as follows MME GenericParams_ t params MME LENGTH ThreeParameters ll MME PARAMS params ParamOne MME PARAMS params ParamTwo MME PARAMS params ParamThree MME_INDEXED_PARAM MME_PARAM MME_PARAM_SUBLIST MME_LENGTH_BYTES ll Iz 2 3 8182595 Rev 5 63 224 MME API UM1112 MME_LENGTH_BYTES Return the length of a parameter array in bytes Definition include lt mme h gt define MME LENGTH BYTES name Arguments name Name of the parameter array Description Find the length of a named parameter array in bytes Returns The length of the named parameter array in bytes See also MME_INDEXED_PARAM MME_LENGTH MME_PARAM MME_PARAM_SUBLIST 3 64 224 8182595 Rev 5 UM1112 MME API MME_ModifyTuneable Modify system wide configuration values Definition include lt mme h gt MME ERROR MME ModifyTuneable MME tunable _t key MME UNIT value Arguments key Specify the tuneable value to be modified value The new value for the tuneable Returns MME INVALID ARGUMENT The supplied key is invalid or not support on this operating system MME SUCCESS The tuneable has been successful upda
155. hey will not synchronize or communicate with each other until necessary ICS _cpu_init also takes a flag argument ICS INIT CONNECT ALL and setting this flag causes initialization to be synchronized between the CPUs In this case all CPUs must call ICS cpu_init setting ICS INIT CONNECT ALL and each call will only return when all CPUs defined in the CPU set have successfully called ICS_cpu_init If one or more CPUs in the set fail to call ICS_cpu_init then the blocked calls will eventually return after a pre defined timeout Table 14 Initialization and termination functions Function name Description ICS_cpu_init Initialize the ICS system on a CPU ICS_cpu_term ICS_cpu_info Terminate the ICS system on a CPU Query the ICS CPU configuration ICS _cpu_termis called when an application is shutting down and is used to close down the local ICS system ICS_cpu_info identifies the caller s logical CPU number and the also the set of CPUs running ICS defined in a bitmask 3 8182595 Rev 5 UM1112 Overview of the inter core system ICS 5 3 3 Channel based communication The lowest level communication primitive provided by ICS is that of a channel A channel consists of a point to point unidirectional FIFO first in first out queue of message slots used for communicating between a pair of CPUs The length of the FIFO and the size of the slots can be chosen on creation APIs for data sending and for
156. hich a command should be executed MME_SendCommand 8182595 Rev 5 Valid priorities for command execution 101 224 MME API UM1112 MME_ProcessCommand_t Process the transformer command Definition include lt mme h gt MME ERROR MME ProcessCommand_t void context MME Command_t commandInfo Arguments context Transformer context commandInfo Data associated with the command Returns MME SUCCESS Success MME INVALID HANDLE The handle does not refer to an existing transformer MME INVALID ARGUMENT The commandInfo argument is invalid MME INVALID COMMAND The command embedded in commandInfo is invalid MME NOMEM The result of the processing of the input data does not fit in the provided memory space MME_NOMEM The result of the processing of the input data does not fit in the provided memory space MME DATA UNDERFLOW Returned when MME reaches the end of the input buffer without being able to produce the requested output Description This function performs one of the following operations commence a new transform set the transformer parameters handle the submission of data buffers Comments Call type blocking function call See also Chapter 3 Writing an MME transformer on page 34 102 224 8182595 Rev 5 ky UM1112 MME API MME_ScatterPage t Describe a scatter page Definition include lt mme h gt typedef struct void Page p MME UINT Size MME _UINT BytesUsed MME_UINT Fla
157. ilbox MBOX1 1 interrupt unsigned int amp 0S21 INTERRUPT_MAILBOX WE own this one flags 0 base void MBOX1 ADDR 0x100 Audio LX Mailbox MBOX1 2 interrupt 0 flags 0 base void MBOX3_ADDR ST40 ESTB Mailbox MBOX3 1 interrupt 0 flags 0 base void MBOX3 ADDR 0x100 ST40 ESTB Mailbox MBOX3 1 interrupt 0 flags 0 hi unsigned int bsp_mailbox_count sizeof bsp mailboxes sizeof bsp mailboxes 0 A 3 3 Reset and boot addresses 3 Filename stx7141 st40 reset c include lt bsp _bsp h gt include sti7141reg h Reset bypass mask must not unset masked eCM reset as reset will be asserted struct bsp_reg_mask bsp_sys_reset_bypass STI7141_SYSCONF SYS CFGO8 1 lt lt 3 1 lt lt 4 1 lt lt 3 8182595 Rev 5 209 224 ICS board support package UM1112 A 3 4 210 224 STI7141_SYSCONF_SYS_CFGO9 1 lt lt 28 1 lt lt 27 1 lt lt 27 i Size of the above array unsigned int bsp _sys_reset_bypass_ count sizeof bsp _sys_reset_bypass sizeof bsp_sys_reset_bypass 0 struct bsp boot address reg bsp sys boot _registers STI7141_SYSCONF_ SYS CFGO8 3 OxFFFFO000 eSTB STI7141_SYSCONF SYS CFG04 3 OxFFFF8000 eCM STI7141_SYSCONF SYS CFG26 0 OxFFFFFFO0O audio STI7141_SYSCONF_ SYS CFG28 0 OxFFFFFF00 video
158. info 0 0005 202 bsp _cpu_name 00 205 210 F BSP CPUS ate Ga cease naa etn Wag T conceaiaa 26 BSP_INCDIR environment variable 202 FlagsOut onoonoae 26 PSP AID SGU desairortgii A03 209 209 FOURC Olona aus iriiri riria Sada 36 bsp_mailboxes 203 208 209 Frame based transformer 31 39 bsp _mbox_regs 200 000 203 bsp _reg_mask 0 005 204 BSP_SRCDIR environment variable 202 H bsp_sys_boot_enable io ada anan Se thane 204 210 Host processor bsp_sys_boot_registers 204 210 MME eaaa aaie suede uh andes 15 bsp_sys_reset_bypass 204 209 210 bsp_sys_reset_bypass_count 204 210 l bsp_sys_reset_register 210 bsp_sys_reset_registers 204 ICS sks abe saatiiade cs i beads 110 124 Buffer channel communication 115 MME vcs cvee oS deals AAE ace oc 23 26 CPU watchdog support 123 Build debug logging support 124 source code 1 ee 9 dynamic module loading 122 testsuite zseaseriarurii Katies eae dea 10 initialization 0200005 111 memory management 119 c name Server 0 eee 122 port communication 117 Cache ICS_channel_alloc 115 116 149 MME iia iene eae ee ee 23 26 ICS_CHANNEL_CALLBACK 151 Companion processor ICS_channel_close
159. inter to an ICS_DYN sized handle which is used to return the allocated dynamic module handle 3 166 224 8182595 Rev 5 UM1112 Inter core system ICS API ICS_dyn_load_image Load a dynamic ELF module from a memory image Definition Arguments Returns Errors Context Description 3 include lt ics h gt ICS_ERROR ICS dyn_load_image ICS _UINT cpuNum ICS CHAR image ICS SIZE imageSize ICS_UINT flags ICS DYN parent ICS DYN handlep cpuNum Target CPU number image Base address of the dynamic ELF module imageSize Size of the dynamic ELF module image flags Various flag bits which affect behavior parent Handle of parent dynamic module handlep Returns dynamic module handle ICS SUCCESS Successfully loaded the dynamic module handlep Allocated dynamic module handle on success ICS INVALID ARGUMENT An invalid argument or ELF file was supplied ICS NOT CONNECTED Target CPU is not connected ICS _ENOMEM Failed memory resource allocation ICS_SYSTEM_ERROR A system error occurred ICS SYSTEM TIMEOUT A communications operation timed out Callable from task context only ICS dyn _load_image is used to take a dynamic ELF module file relocatable library image on the calling CPU and relocate it so that it can be executed on the target CPU On successful completion a dynamic module handle is returned to the caller in the handlep argument The ICS dynamic module system is layered on top
160. invalid for example out of range null pointer incorrect structure size MME UNKNOWN TRANSFORMER The requested transformer does not exist MME INVALID COMMAND The command code is invalid 92 224 8182595 Rev 5 ky UM1112 MME API 3 MME TRANSFORMER NOT RESPONDING The transformer is not responding to requests for status MME HANDLES STILL OPEN The operation cannot complete until all transformer handles have been closed MME COMMAND STILL EXECUTING MME COMMAND ABORTED MME DATA UNDERFLOW MME DATA OVERFLOW MME ICS ERROR MME INTERNAL ERROR MME NOT IMPLEMENTED The operation cannot complete until the transformer is idle The command did not complete because it was explicitly aborted by the user Insufficient input data to generate a frame of output Output buffers are too small to store the transformed data MME _ TRANSFORM DEFERRED A transform has been placed in the deferred state by a transformer ICS underlying MME has reported an error There is an internal inconsistency The function is not implemented MME_COMMAND_TIMEOUT An issued command timed out 8182595 Rev 5 93 224 MME API UM1112 MME_Event_t Valid event codes associated with a command Definition include lt mme h gt typedef enum MME COMMAND COMPLETED EVT MME DATA UNDERFLOW EVT MME NOT ENOUGH MEMORY EVT MME TRANSFORMER TIMEOUT MME Event _t Description Event codes associated with a command Events a
161. ion is supplied with a parameter defined by the ICS_port alloc call plus a pointer to a message descriptor which supplies the data sent Normally the handler will process the message and return ICS_SUCCESS If the handler is unable to consume the buffer it will return ICS _ FULL and the message will be held on the port message queue after which ICS_msg_ recvorICS msg_post must be called to process the message The functions ICS_msg_recv ICS msg_post ICS msg cancel ICS msg _test and ICS msg_wait are used for receiving from a process ICS_msg_recv can be used to synchronously receive a message from a port it blocks on the port and returns a new message in a message descriptor when it arrives ICS_msg_post posts an asynchronous receive operation to the port supplies a message descriptor to hold the message when it arrives and returns an event handle which can be used by ICS_msg_test and ICS _ msg wait to test or wait for the arrival of the message ICS_msg_cancel can be used to cancel an asynchronous port receive operation New incoming messages will always be matched to the posted receiving descriptors in the order the ICS_msg_post functions were called 3 8182595 Rev 5 UM1112 Overview of the inter core system ICS 5 5 3 Memory region management Functions are provided in ICS to manage memory regions in the SoC s memory these can be defined and mapped for use by all the CPUs allowing common regions of physical memo
162. ions may not be available on the other CPUs Once ICS is up and running on all CPUs there is no significant distinction between a master and a companion so that a companion CPU could communicate with another companion CPU and could load dynamic modules relocatable libraries to another companion CPU if the ICS system has been configured to allow this and this may depend on the design of the SoC The master CPU in an ICS system would typically run the nameserver service and monitor and manage the rest of the system in the event of a fault but it is possible to delegate these functions to other CPUs in the SoC ina system design In the current implementation of ICS the master CPU may be running Linux or 0 21 OSPlus The companion CPUs are expected to be running OS21 A dual or multi core SMP processor under the control of a single OS would be considered a single CPU for the purposes of this definition Each CPU is given a logical number 0 N for the purposes of ICS The logical numbers for the set of CPUs on an SoC are defined in the Multicom BSP or Registry information An ICS function operating on a CPU is given the CPU logical number to which the operation should be applied An ICS function operating on one or more CPUs is given a bitmask in which the bits that are set define the CPUs to which the operation applies 3 8182595 Rev 5 UM1112 Overview of the inter core system ICS CPU query functions Table 9 CPU query fun
163. irtual memory Virtual to Physical to Region 1 hysical virtual Region 1 cached cached Region 1 Region 2 Region 2 Region 2 uncached a uncached Region 3 Region 3 Region 3 cached cached 8182595 Rev 5 121 224 Overview of the inter core system ICS UM1112 5 6 5 7 122 224 Name server The ICS port model is based on named port handles which can be looked up using a central name server This name service has also been exported as a primary API so that programmers can register other data objects and associate them with an ASCII string Table 18 Name server functions Function name Description IcS_nsrv_add Add a named object with the name server ICS nsrv_remove Remove an object from the name server ICS _nsrv_lookup Look up a named object in the name server Functions are provided to add remove and look up names in the central name server Lookups return the associated object handle if a match is found Lookups can also be specified to block if a name is not found in which case they will only return once that name is registered or a specific timeout period has expired This facility can be used to build synchronization points between the ICS CPUs Dynamic module loading ICS provides functions for dynamically loading and unloading code modules relocatable libraries on a companion CPU These are distinct from the basic functions described earlier
164. itCommand has completed successfully it is invalid to issue a subsequent MME_ WaitCommand using the same Cmdtid It is also possible for MME_WaitCommand to return MME_DATA UNDERFLOW or MME DATA OVERFLOW status values In this case the event is set to MME _DATA_UNDERFLOW_EVT or MME_NOT_ENOUGH MEMORY_EVT respectively ky 8182595 Rev 5 UM1112 MME API Comments See also 3 When such an error occurs the driver should respond as appropriate to the error condition it can then subsequently call MME_WaitCommand on the same CmdId If the command does not complete before the specified timeout then MME COMMAND TIMEOUT is returned This error code is also returned if the CPU hosting the transformer fails The event completion code is set to MME _TRANSFORMER_TIMEOUT Setting the Timeout parameter to MME TIMEOUT INFINITE causes MME WaitCommand to block indefinitely for command completion However it returns MME_COMMAND_TIMEOUT if the command is executing on a CPU that is determined to have failed Call type blocking function call MME_SendCommand MME_Command_t MME_CommandEndType_t 8182595 Rev 5 771224 MME API UM1112 MME_Version Query the MME system version string Definition include lt mme h gt const char MME Version void Arguments None Returns A pointer to the MME version string Errors None Context Callable from task and interrupt context Can be called before MME Init Description Return a poi
165. l buffer pointer Returns ICS SUCCESS Successfully consumed FIFO buffer Errors ICS FULL Failed to consume FIFO buffer Context Called from interrupt context only Description This is the channel callback function that is invoked for each entry that is inserted into 3 the channel FIFO It will be called using the same param argument as supplied during ICS_channel_alloc The buffer pointer will point to an area of memory of up to ssize bytes as specified during the ICS_channel_alloc call No protocol is added by the ICS channel interface so the actual buffer size will need to be determined by the programmer Normally the callback function will copy and then consume the FIFO entry by calling ICS_channel_release lIn this case it should return ICS_SUCCESS However if for some reason it is not possible to consume this entry then ICS_ FULL should be returned This will cause the FIFO buffer to be left at the head of the FIFO and to block it No further callbacks will be generated on this channel until it is subsequently unblocked by a call to ICS_channel_unblock 8182595 Rev 5 151 224 Inter core system ICS API UM1112 ICS_channel_close Close a send channel Definition include lt ics h gt ICS_ERROR ICS channel _ close ICS CHANNEL SEND schannel Arguments schannel Send channel handle Returns ICS SUCCESS Successfully closed the send channel Errors ICS NOT INITIALISED ICS not initialized ICS HAN
166. l_send Send a buffer using an ICS send channel Definition Arguments Returns Errors Context Description 3 include lt ics h gt ICS ERROR ICS channel send ICS CHANNEL SEND schannel ICS_VOID buffer ICS SIZE size ICS _UINT flags schannel Send channel handle buffer Channel buffer pointer size Size in bytes of data buffer flags Various flag bits which affect behavior ICS SUCCESS Successfully sent the buffer ICS NOT _INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid send channel handle was supplied ICS NOT _CONNECTED Target CPU is not connected ICS FULL The channel FIFO was full ICS _ENOMEM Failed memory resource allocation ICS _SYSTEM_ERROR A system error occurred Callable from task and interrupt context ICS channel _send sends a data buffer using an open send channel by copying it into the channel FIFO On successful return it is guaranteed that the data will be received by the target CPU task All buffers will be delivered in the order they were sent The size of the data buffer must not exceed the size of the channel FIFO slots as specified in the ICS_channel_alloc call If the channel FIFO is full then ICS_ FULL will be returned In this case it is the programmer s responsibility to re issue the send once the flow control issue has been resolved schannel should be a valid open send channel handle as r
167. llocated nameserver handle is returned 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_nsrv_lookup Lookup a named object in the name server Definition Arguments Returns Errors Context Description 3 include lt ics h gt ICS_ERROR ICS nsrv_lookup const ICS CHAR name ICS_UINT flags ICS LONG timeout ICS _ VOID data ICS SIZE sizep name Name string maximum length ICS NSRV_MAX NAME flags Various flag bits which affect behavior timeout Time in milliseconds to block waiting for a response data Buffer for discovered object data sizep Used to return the discovered object data size ICS SUCCESS Successfully discovered an object in the name server data Buffer where object data is copied on success sizep Discovered object data size ICS NOT INITIALISED ICS not initialized ICS NAME NOT FOUND name was not found in the name server ICS INVALID ARGUMENT An invalid argument was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Callable from task context only ICS nsrv_lookup attempts to discover the named object in the global name server It supports both blocking and non blocking modes of operation In the non blocking mode if the supplied name is not present in the name server then ICS NAME NOT_FOUND will be returned In the blocking mode the call will
168. mer MME TransformerHandle t Handle MME Time_t Timeout Handle Timeout MME SUCCESS MME DRIVER NOT INITIALIZED MME NOMEM MME INVALID HANDLE MME COMMAND TIMEOUT Handle of the targeted transformer Timeout period in milliseconds The ping request was successfully responded to by the target transformer The MME driver has not been initialized The memory required to complete this command is not available The handle does not refer to an existing transformer The ping request was not responded to by the remote transformer within the specified timeout period Send a ping command request to a specific transformer This acts like a very high priority command to the target transformer and hence should be processed as the very next command the transformer executes If the command has not responded within the specified timeout then MME_COMMAND_ TIMEOUT is returned The Timeout value should be carefully chosen so it does not produce false failures due to the target transformer or CPU simply taking too long to respond Call type blocking function call MME_SendCommand MME_WaitCommand MME_Time_t 8182595 Rev 5 3 UM1112 MME API MME_RegisterMemory Register memory region with a specific transformer Definition Arguments Returns Description Comments See also include lt mme h gt MME ERROR MME RegisterMemory MME TransformerHandle t Handle void Base
169. mflags member indicates the data attributes For IcS INLINE messages the data will be available in 8182595 Rev 5 ky UM1112 Inter core system ICS API 3 the payload buffer and the rdesc data member will reflect this fact For ICS CACHED and ICS_UNCACHED messages the corresponding virtual address mapping that is cached or uncached will be supplied in the data member For ICS PHYSICAL messages the physical address of the sender s original data buffer will presented in the rdesc data member 8182595 Rev 5 175 224 Inter core system ICS API UM1112 ICS_msg_send Send a message buffer to a port Definition Arguments Returns Errors Context Description 176 224 include lt ics h gt ICS ERROR ICS_msg_ send ICS PORT port ICS VOID buffer ICS MEM FLAGS mflags ICS SIZE size ICS UINT flags port Port handle buffer Source data buffer mflags Destination data buffer memory attributes size Source data buffer size flags ICS message and send flag bits see Table 27 ICS SUCCESS Successfully sent message ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid port handle was supplied ICS PORT _CLOSED Port has been closed ICS NOT CONNECTED Target CPU is not connected ICS FULL An inter CPU FIFO was full ICS _ENOMEM Failed memory resource allocation ICS_SYSTEM_ERROR A system error occurred Callabl
170. mposed of one or more scatter pages A scatter page describes a single sequential group of memory locations or more specifically a base pointer and a size A data buffer comprised of a single scatter page is a linear buffer while a data buffer consisting of multiple scatter pages is a scattered buffer A scatter page is represented by the structure MME ScatterPage t Figure 5 A scattered data buffer Completely filled WTA 4096 byte scatter page Half filled i Half filled 12288 byte J 4096 byte data buffer scatter page Empty p Se 4096 byte scatter page Although both linear and scattered buffers are properly handled by the MME API some transformers are not able to efficiently support scattered buffers For example using 8182595 Rev 5 23 224 Using the MME API UM1112 2 5 1 2 5 2 Note Note 24 224 scattered buffers makes it difficult to delegate work to accelerators that only support linear DMA Allocating data buffers Data buffers can be allocated and freed using the following functions MME ERROR MME AllocDataBuffer MME TransformerHandle t Handle MME UINT Size MME AllocationFlags t Flags MME DataBuffer t DataBuffer pp MME _ ERROR MME FreeDataBuffer MME DataBuffer _t DataBuffer p Buffers allocated using MME_AllocDataBuffer come from a common buffer pool which is of a fixed size The size of this buffer pool can be varied by adjusting the tuneable v
171. must not refer to the CPU on which the function is being called in this case an error is returned The running CPU must have the capability to control the targeted CPU otherwise an error is returned Other ics helper functions are given in Table 12 and Table 13 Table 12 Information functions Function name Description ics_cpu version Query the ICS system version string ics_err_str Return an ICS error string 3 8182595 Rev 5 113 224 Overview of the inter core system ICS UM1112 5 2 3 114 224 Table 13 Heap functions Function name ics heap create Description Create an ICS heap ics heap_destroy Destroy an ICS heap ics heap alloc Allocate a buffer from an ICS memory heap ics heap_free Release a buffer back to an ICS heap ics heap _ base Query ICS heap for virtual base address ics heap pbase Query ICS heap for physical base address ics heap_size Query ICS heap for size The ics heap functions carry out typical heap operations for ICS heaps and are intended to be used by an application in conjunction with the memory region functions for buffer management ICS initialization and termination Code running on each of the CPUs in the SoC has to initialize the ICS system on that CPU before it can use ICS functions This is done with the function IcS_cpu_init All CPUs wishing to communicate must first call this function However t
172. n Currently the ICS is supplied with BSPs for a limited number of SoCs Appendix A ICS board support package on page 201 describes how to create a BSP for other SoCs 3 8182595 Rev 5 UM1112 Using the MME API 2 2 1 Using the MME API Overview The MME API provides a means for an application program running on the host processor to control and manipulate a codec or similar media transformer running either on the same processor or on a different companion processor The aim of a companion processor is to assist the host in transforming data in real time and it communicates with the host using the ICS communication interface see Chapter 5 Overview of the inter core system ICS on page 110 Both host and companion transformers may optionally make use of hardware accelerators to off load some or all of the work The MME API remains the same independent of the location or type of the transformer effectively hiding the potentially complex structure of the system from the application The MME API is intended to form part of the driver layer of typical multimedia software stacks See Figure 1 on page 1 Transformers and transformer instances Within the MME system the division of roles between the host and companion processors is logically described by what are known as transformers Transformers are named software modules that normally reside in the companion processors A companion CPU will register a transformer for eac
173. n properties In general the use of MME_ALLOCTION_UNCACHED should be used with caution since it is potentially harmful to performance Its use should be limited to applications where the underlying MME data buffer is used outside of the MME interface by cache incoherent hardware Even in this case it is preferable to use cached memory and manage the caches if the host performs any reads or writes to the data buffer Fields MME ALLOCATION PHYSICAL Require the allocated memory to be contiguous within its physical address space MME ALLOCATION CACHED Require the allocated memory to be accessed through the cache on the host processor MME ALLOCATION UNCACHED Require the allocated memory to be accessed directly by the host processor See also MME_Command_t 80 224 MME_SendCommand 3 8182595 Rev 5 UM1112 MME API MME_Command_t Defines the parameters of the command sent to a Definition include lt mme h gt typedef struct transformer as a number of sub structures MME _UINT StructSize MME _ CommandCode_t CmdCode MME _CommandEndType_t CmdEnd MME Time_t DueTime MME_UINT NumberInputBuffers MME _UINT NumberOutputBuffers MME DataBuffer t DataBuffers p MME CommandStatus_t CmdStatus MME_UINT ParamSize MME GenericParams t Param_p MME _Command_t Description Defines the parameters of the command passed to the MME_SendCommand function While the command is in progress the master copy of all data structu
174. n running the host under Linux debug logging can be enabled in the same way that is by compiling the Multicom 4 kernel drivers having set DEBUG_CFLAGS appropriately The debug logging level and output channel can then be controlled by using the kernel module parameters supplied to both the ICS and MME kernel modules For example insmod ics ko debug _flags 1 debug_chan 5 insmod mme ko debug_flags 1 Tuneable parameters MME allows parameters such as thread priority to be tuned without recompiling Multicom components The function to modify tuneable parameters is MME ERROR MME ModifyTuneable MME Tuneable t key MME UINT value Each call to this function allows a single tuneable value to be updated See MME_ModifyTuneable on page 65 for further details 8182595 Rev 5 217 224 ICS Linux module parameters UM1112 Appendix D ICS Linux module parameters D 1 D 2 D 3 218 224 This appendix describes the installation parameters that can be supplied to the ICS kernel module Support for declaring ICS regions on the module load The parameters used for this purpose have the following syntax regions region region region lt bpa2name gt lt phys_base gt lt size gt Where lt bpa2name gt is the ASCII name of the bpa2 partition for example LMI_VID or LMI_Sys Otherwise the physical base address and size of a region can be specified directly When configured these regions are mapped into all CPUs as cached
175. nd a set of test suites tailored to support certain ST SoCs In addition sample board support packages BSPs are provided This chapter explains how to build the sources and test suites and then to compile and link the Multicom 4 libraries before running the test suites under the required OS It also explains how to use the sample BSP as a template for creating new BSPs Multicom 4 has been developed and tested for target CPUs running both OS21 and Linux STLinux R2 3 and R2 4 Code organization The release contains two source packages e os21 Multicom 4 release for OS21 based targets e linux Multicom 4 release for Linux based targets Unpack the Multicom distribution on a suitable host machine which has the appropriate target toolsets installed See Section 1 1 2 on page 9 for a list of applicable toolsets These toolsets must be included in your PATH The main code is split between two top level directories e source e test The source directory contains all the code for the ICS and MME system libraries The test directory contains many self tests which test each subsystem of ICS and MME The Multicom distribution contains a deep directory structure An overview of these directories is listed in Table 7 Table 1 The distribution directories Directory Contains docs Product documentation source include C header files used by every processor source src bsp BSP configuration files for each SoC source src ics Complete
176. nd since this is how their data buffers are delivered Like all other commands the MME_SEND_ BUFFERS command should return an error code if the command structure is in some way invalid It is also permissible to return an error if the transformer instance s buffer queue is full If the processing function returns an error for a send buffers command the application will be immediately notified 3 8182595 Rev 5 41 224 Writing an MME transformer UM1112 Note Note 3 5 42 224 Otherwise on receipt of an MME_SEND BUFFERS command a streaming transformer must store the command within its context structure ready for it to be used by the corresponding MME_TRANSFORM command The MME_SEND BUFFERS command interrupts the currently executing command in order to deliver the buffers The implementation of the send buffers command should therefore perform the smallest amount of work possible in order to minimize the cost of this interruption Examination of data buffers and chaining of scatter pages are best left to the MME TRANSFORM command After storing the MME_SEND BUFFERS command in the context structure the processing function should return MME SUCCESS At this point the command will be deferred until it is marked as completed through execution of a MME_ TRANSFORM command When the MME_TRANSFORM command by calling MME _NotifyHost marks a MME SEND BUFFERS command as completed it guarantees that it will no longer access any part
177. ndex of the parameter to extract An 1value an object that can be assigned to whose type is selected by the named parameter Extract a indexed named parameter from a parameter array This macro uses other special purpose macros or named constants to process the name For example the following macros define an indexed parameter name called ThisIsIndexed enum MME OFFSET ThisIsIndexed 2 define MME TYPE ThisIsIndexed U32 This parameter can be extracted as follows MME INDEXED PARAM params ThisIsIndexed 0 OxAC3 MME INDEXED PARAM params ThisIsIndexed 1 OxDDD MME_PARAM MME_LENGTH MME_PARAM_SUBLIST 8182595 Rev 5 59 224 MME API UM1112 MME_Init Initialize the MME infrastructure Definition include lt mme h gt MME ERROR MME Init void Arguments None Returns MME SUCCESS The operation completed correctly MME DRIVER_NOT_INITIALIZED The MME driver could not be initialized because underlying resources were not initialized yet MME DRIVER_ALREADY INITIALIZED MME Init has been called already MME _NOMEM The memory required to complete this command is not available Description Initialize the MME infrastructure This function must be called prior to calling any other MME functions It must be called at least once on each processor and by each Linux user mode process Once initialized further calls return MME DRIVER ALREADY INITIALIZED See also MME_InitTransformer 60 224 MME_Term 3
178. nds and transformers that are hosted on the failed CPU are terminated Further facilities are provided to allow the programmer to Ping the remote transformers periodically See MME_PingTransformer on page 70 allowing them to check that the target transformer has not hung or got stuck in an infinite loop Using these facilities the device driver writer should be able to detect and recover from an unexpected companion CPU failure Generally this involves tidying up all the device driver state associated with the failed CPU and transformer instances and then reloading and restarting the code on the companion CPU Multicom cannot recover from a failure of the host CPU or errors which cause a system wide lockup Also if a companion failure results in corruption of memory belonging to the host CPU then it may fail subsequently a The technicalities of aborting a deferred command is discussed in detail in Section 3 4 2 Deferred commands on page 40 8182595 Rev 5 29 224 Using the MME API UM1112 2 9 2 9 1 2 9 2 2 9 3 30 224 Types of commands There are three types of command that can be issued through a call to MME_SendCommand e transform data e provide additional data buffers e alter global parameters A command type is selected by setting the MME _CommandCode_t field in the MME Command _t structure These types are described in Section 2 9 1 through to Section 2 9 3 Transforming data Data transform
179. nion res MME Init Register the transformers active on this CPU res MME RegisterTransformer com st mcdt mme test_transformer abortFunc getCapabilityFunc initFunc processCommandFunc termFunc Managing transformer lifetimes Transformer instances can be created and destroyed using the following functions MME ERROR MME InitTransformer const char name MME TransformerInitParams_t params_p MME TransformerHandle t handle_p MME ERROR MME TermTransformer MME TransformerHandle_ t handle _p The name argument specifies the name of the previously registered transformer params_p is used to specify one of five priority levels for the transformer together with details of the callback function used to communicate any events associated with this transformer and its commands Additionally the parameter structure may contain a pointer to transformer specific parameters containing any initial state the transformer may require See Section 2 6 Application and transformer specific data on page 27 and Section 3 7 Parameter passing on page 44 If MME InitTransformer returns successfully then handle_p is supplied with a handle used to issue commands and terminate the transformer Once initialized a transformer can execute an arbitrary number of commands before finally being terminated MME TermTransformer is used to destroy a transformer instance thus freeing any resources used by the transformer 8182595 Rev 5 ky
180. ns ICS SUCCESS Successfully de registered the named object Errors ICS_NOT_INITIALISED ICS not initialized ICS HANDLE INVALID An invalid object handle was supplied ICS NAME NOT FOUND The object is not present in the name server ICS INVALID ARGUMENT An invalid argument was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred ICS SYSTEM TIMEOUT Failed to communicate with the name server Context Callable from task context only Description ICS nsrv_remove removes a previously registered object from the global ICS 3 name server If the supplied object is not present in the name server then ICS_NAME_NOT_FOUND is returned handle should be a valid name server object handle as returned by ICS_nsrv_add Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 183 224 Inter core system ICS API UM1112 ICS_port_alloc Allocate an ICS port Definition Arguments Returns Errors Context Description 184 224 include lt ics h gt typedef ICS ERROR ICS PORT CALLBACK ICS PORT port ICS VOID param ICS MSG DESC rdesc ICS_ERROR ICS port_alloc const ICS CHAR portName ICS PORT CALLBACK callback ICS_ VOID param ICS _UINT ndesc ICS_UINT flags ICS PORT portp portName Port name to be allocated or NULL callback Callback function to be associated with this port param Parameter to be supplied to
181. nsformerCapability_t structure that will be filled with the capability of the corresponding transformer MME SUCCESS The operation completed correctly MME DRIVER_NOT_ INITIALIZED The MME driver has not been initialized MME UNKNOWN TRANSFORMER No transformer of the specified name exists MME INVALID ARGUMENT TransformerCapability_p is invalid MME NOMIPS CPU low in resources to run transformer Return capability and requirement for a given transformer type The error code MME_NOMIPS is returned if MME_GetTransformerCapability finds the CPU too low in resources to run the transformer Additional status information is returned in the AdditionalStatus field of the MME TransformerCapability_t structure which can be MME_NOMIPS or MME _NOMEM The following fields of the MME_TransformerCapability_t structure must be initialized prior to calling this function StructSize TransformerInfoSize and TransformerInfo _p All subsequent fields will be filled in by MME as a result of the call Call type blocking function call MME_TransformerCapability_t 3 8182595 Rev 5 UM1112 MME API MME_INDEXED_PARAM Extract indexed parameter Definition Arguments Returns Description See also 3 include lt mme h gt define MME INDEXED PARAM params name index params Pointer to a parameter array of type MME GenericParams t name Name of the parameter to be extracted from the array index I
182. nt sets of 4 x 32 bit mailbox registers The second set is at offset 0x100 from the base address of the Mailbox IP struct bsp_mbox_regs void base unsigned int interrupt unsigned int flags Table 29 Mailbox table structure Structure member name Description base Physical base address of the mailbox set Interrupt request number or address on OS21 interrupt associated with this mailbox if local Set to 0 for remote mailboxes flags Various flag bits The following declarations need to be made in the BSP normally found in mbox c extern unsigned int bsp_mailbox_count extern struct bsp_mbox_regs bsp_mailboxes Where bsp_mailboxes is the array of mailbox definitions and bsp_mailbox_ count is set to the number of entries in that array Reset and boot addresses These data structures are used to define for each CPU the core reset and boot information so that ICS can load and start each CPU The entries in these tables must be synchronized with entries in the CPU table described in Section A 2 1 on page 202 8182595 Rev 5 203 224 ICS board support package UM1112 204 224 Boot address Boot address info struct bsp_boot_address reg volatile unsigned int address int leftshift unsigned int mask Table 30 Boot address structure Structure member name Description address For each CPU SYSCONF boot register address leftshift Left shift t
183. nter to the MME version string 78 224 This string takes the form major number minor number patch number text That is a major minor and release number separated by decimal points and optionally followed by a colon and a text string 3 8182595 Rev 5 UM1112 MME API 4 2 MME constants enums and types MME_AbortCommand_t Abort a transform command Definition include lt mme h gt MME ERROR MME_ AbortCommand_t void context MME CommandId_t commandId Arguments context Transformer context data commandiId The command identifier Returns MME SUCCESS Success MME INVALID ARGUMENT An invalid commandId parameter has been specified MME INVALID COMMAND The transformer is active and cannot be aborted Description Abort a transform command 3 This function will be called when an abort command request is made on the host and the command has been submitted to the transformer The behavior is transformer specific transformers that do not support command aborting must return MME INVALID COMMAND 8182595 Rev 5 79 224 MME API UM1112 MME_AllocationFlags t Describes properties of allocated memory Definition include lt mme h gt typedef enum MME ALLOCATION PHYSICAL MME ALLOCATION CACHED MME ALLOCTION UNCACHED MME AllocationFlags t Description Flags to describe the memory properties of allocated memory Flags may be or ed together to obtain sensible combinations of allocatio
184. ntryAddrp Returns loaded object ELF start entry address ICS SUCCESS Successfully unpacked the ELF image entryAddrp ELF code start entry address ICS INVALID ARGUMENT An invalid argument or ELF image was supplied ICS _ENOMEM Failed memory resource allocation ICS SYSTEM ERROR A system error occurred Callable from task context only Can be called before ICS_cpu_init ics load_elf image is used to unpack an ELF memory image on the master CPU so that it can be executed on the Slave Companion CPUs On successful completion the ELF start entry address is returned to the caller in the entryAddrp argument image should reference a complete ELF file image Currently no flags bits are defined and this parameter must be set to zero 3 8182595 Rev 5 UM1112 Inter core system ICS API 6 2 Note ICS_ function definitions This section provides detailed descriptions of the ICS_ functions The function ICS_cpu_init or ics _cpu_init must be called on the current CPU before any function beginning with ICS_ is called ICS_channel_alloc Definition Arguments Returns Errors Context ky include lt ics h gt Allocate an ICS communications channel typedef ICS ERROR ICS CHANNEL CALLBACK ICS CHANNEL channel ICS VOID param void buffer ICS VOID param ICS _ VOID base ICS _UINT nslots ICS UINT ssize ICS_UINT flags ICS_ CHANNEL channelp callback param base nslots
185. o be applied to boot address mask Mask to be applied to boot address Reset address struct bsp_reg_mask volatile unsigned int address unsigned int mask unsigned int value Table 31 Register address structure Structure member name Description address Register SYSCONF address mask Mask to be applied to register value Data value to be applied to the register The following declarations need to be made in the BSP normally found in reset c extern extern extern extern extern struct bsp boot_address_reg bsp_sys_boot_registers struct bsp reg mask bsp _sys_reset_ bypass unsigned int bsp sys reset bypass count struct bsp_reg_ mask bsp_sys_boot_enable j struct bsp reg mask bsp _sys_reset_registers j Where bsp_boot_address_ registers is an array of boot address definitions for each CPU core in the SoC The bsp_ sys reset bypass array defines all the SYSCONF boot reset bypass registers and bit patterns necessary to allow individual CPUs to be reset The bsp sys reset bypass count variable should be set to the number of entries in this array 8182595 Rev 5 ky UM1112 ICS board support package Note A 2 4 3 The bsp_sys_boot_enable table defines for each CPU the SYSCONF boot enable registers and bit pattern to cause each CPU to boot The bsp sys reset registers table defines for each CPU the SYSCONF reset registers and bit patterns to caus
186. o the cyclic buffer of that CPU 3 8182595 Rev 5 UM1112 Inter core system ICS API 6 Inter core system ICS API This chapter describes the ICS API in terms of its functions and macros The functions are listed in alphabetical order Functions beginning with ics_ are listed in Section 6 1 ics_ function definitions and functions beginning with 1cs_ are listed in Section 6 2 ICS_ function definitions on page 149 Macro definitions are listed in Section 6 3 Macro definitions on page 200 Note The function ICS_cpu_init or ics _cpu_init must be called on the current CPU before any function beginning with ICS_ is called The following ICS functions are supported on Linux user space e ics _cpu_init ICS_cpu_init ICS_cpu term ICS_region_add ICS_region_remove 3 8182595 Rev 5 125 224 Inter core system ICS API UM1112 6 1 ics_ function definitions This section provides detailed descriptions of the ics_ functions ics_cpu_init Initialize the ICS system on a CPU Definition include lt ics h gt ICS_ERROR ics cpu_init ICS UINT cpuNum ICS VLONG cpuMask ICS _UINT flags Arguments cpuNum The logical CPU number of calling CPU cpuMask Bitmask of participating CPUs flags Debug channel flag bits see Table 22 Returns ICS SUCCESS Successfully initialized Errors ICS ALREADY INITIALISED ICS is already initialized ICS ENOMEM Failed memory resource allocation ICS SYSTEM ERR
187. oad 218 D 2 Support for declaring ICS companion firmware on the module load 218 D 3 Support for contiguous allocations from a named BPA2 memory partition 218 Revision history 2 sdcadhewtetaseed au a a ai aa a a a a E oe oteee ee eceae 219 J 8182595 Rev 5 5 224 Preface UM1112 Preface Comments on this manual should be made by contacting your local STMicroelectronics sales office or distributor Terminology The first ST Micro Connect product was named the ST Micro Connect it is now known as the ST Micro Connect 1 and the term ST Micro Connect is used to refer to the family of ST Micro Connect devices The ST Micro Connect 2 replaces the ST Micro Connect 1 These names are abbreviated to STMC STMC1 and STMC2 Conventions used in this guide General notation The notation in this document uses the following conventions sample code keyboard input and file names variables code variables and code comments e equations and math e screens windows dialog boxes and tool names e _ instructions Hardware notation The following conventions are used for hardware notation e REGISTER NAMES and FIELD NAMES e PIN NAMES and SIGNAL NAMES Software notation Syntax definitions are presented in a modified Backus Naur Form BNF unless otherwise specified e Terminal strings of the language that is those not built up by rules of the langu
188. of that command including its data buffers Underflow and insufficient memory handling When a streaming transformer has insufficient input data to continue it is required to emit MME DATA UNDERFLOW_EVT by using MME NotifyHost Similarly if there is insufficient output data it is required to emit MME_NOT_ENOUGH_MEMORY_EVT In both cases after emitting an event the transformer must then use an operating system primitive such as a semaphore to suspend execution of the current thread The transformer must not busy wait as this will disrupt processing at lower priorities When an MME_SEND_ BUFFERS command is received that permits the processing of the command to continue the transformer should use the operating system primitive to wake up the previously blocked thread Aborting commands The transformer must implement a function that permits commands to be aborted This function must be compatible with the function pointer type MME_AbortCommand_t which is an argument of MME_RegisterTransformer typedef MME ERROR MME AbortCommand_t void context MME _CommandId_t commandId MME AbortCommand_t is called as a result of an application call to MME Abort Command see Section 2 7 1 Aborting commands on page 29 A call to this function is not a demand to abort the command but a request that the transformer may in certain circumstances choose to ignore If the transformer is not able to abort the command it should return MME_ INV
189. of the rl library provided by the ST Micro Toolsets Much more detail can be found in the relevant Toolset manuals As a dynamic module is loaded into the target CPU the ICS system will automatically call a function named module init if one is present in the loaded module cpuNun is the logical target CPU number of where the dynamic module should be loaded image should be a local memory address where the ELF dynamic module image can be found imageSize should be size of the ELF dynamic module image in bytes 8182595 Rev 5 167 224 Inter core system ICS API UM1112 168 224 Currently no flags bits are defined and this parameter must be set to zero parent is the ICS_DYN handle of the parent module of the one being loaded If no parent exists then it can be supplied as a zero handle If a non zero parent handle is supplied then the new module will be linked against that module in the target CPU providing symbol inheritance from the parent module For further details on symbol inheritance see the rl toolkit manual handlep should be a non NULL pointer to an ICS_DYN sized object which is used to return the allocated dynamic module handle 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_dyn_unload Unload a previously loaded dynamic ELF module Definition include lt ics h gt ICS_ERROR ICS dyn_unload ICS DYN handle Arguments handle Handle of the dynamic module to be unloaded Returns IC
190. og reprime reprimes a watchdog handler that has previously 3 triggered Once a watchdog for a particular CPU has been triggered the callback handler for that CPU will not be issued again until it has been reprimed by calling this function handle should be a valid watchdog handle as allocated by ICS_watchdog_add cpuNum should be the logical number of the CPU for which watchdog monitoring is to be resumed 8182595 Rev 5 199 224 Inter core system ICS API UM1112 6 3 Macro definitions This section provides detailed descriptions of the ICS macros These macros can be used by the programmer to determine at compile time which version of the ICS system is being used ICS_VERSION C language macro describing the ICS version Definition include lt ics h gt define ICS VERSION MAJOR MINOR PATCH Description ICS VERSION is a macro that takes a major minor and patch level as arguments and generates a version code that can be compared against ICS_VERSION_CODE For example He ICS VERSION CODE gt ICS VERSION 1 1 0 Call an API added in V1 1 0 endif ICS_VERSION_CODE C language macro describing the ICS version Definition include lt ics h gt define ICS VERSION CODE Description ICS VERSION CODE is the current ICS version code 3 200 224 8182595 Rev 5 UM1112 ICS board support package Appendix A ICS board support package A 1 Introduction The ICS BSP is used to configur
191. on transformer specific 8182595 Rev 5 87 224 MME API UM1112 See also MME_Command_t MME_Command State_t MME_SendCommand 3 88 224 8182595 Rev 5 UM1112 MME API MME_DataBuffer_t Data buffer structure as returned by MME_AllocDataBuffer Definition Description Fields See also 3 include lt mme h gt typedef struct MME_UINT StructSize void UserData_p MME _UINT Flags MME _UINT StreamNumber MME _UINT NumberOfScatterPages MME ScatterPage t ScatterPages p MME UINT TotalSize MME _UINT StartOffset MME DataBuffer t Definition of one possibly scattered buffer belonging to one stream A data buffer consists of a list of one or several scatter pages Each page describes a contiguous linear memory block giving the transformer a memory space to work with StructSize UserData_p Flags StreamNumber NumberOfScatterPages ScatterPages p TotalSize StartOffset MME_ScatterPage_t MME_Command_t Size of the structure in bytes Application specific data to aid data structure lookup from callbacks Buffer specific flags Identifies the stream to which the buffer belongs Number of scatter pages the buffer is composed of that is the number of entries of the MME ScatterPage_t array Pointer to an array of scatter pages Amount of memory available for this buffer that is the sum of the memory size of the scatter pages this buffer comp
192. operation and how soon the CPU starts executing code is system dependant It is an invalid operation to attempt to issue this call against the calling logical CPU number entryAddr should be a valid code start address for the target CPU See ics_load_elf_file and ics_load_elf_image cpuNum should be the logical ICS CPU number of the CPU to be started Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 133 224 Inter core system ICS API UM1112 ics_cpu_type Query the BSP Registry for CPU type Definition Arguments Returns Errors Context Description See also 134 224 include lt ics h gt const char ics_ cpu_type ICS _UINT cpuNum cpuNum Logical CPU number being queried BSP CPU type string NULL CPU not found Callable from task and interrupt context Can be called before IcS_cpu_init ics cpu_type returns the CPU type string associated with the logical CPU number Examples of BSP Registry tables are given in Table 23 on page 128 and Table 24 on page 128 ics opu lookup ics_cpu_name 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_Cpu_version Query the ICS system version string Definition include lt ics h gt const ICS CHAR ics cpu_version void Arguments None Returns A pointer to the ICS version string Errors None Context Callable from task and interrupt context Can be called before ICS_cpu_init
193. ould be called from task context and only be called once per CPU ICS _cpu_init when called with the ICS INIT CONNECT_ALL flag bit value causes the calling CPU to attempt to connect and synchronize with all the other CPUs which are present in the CPU bitmask as derived from the BSP It will block until all the other CPUs have also called ICS_cpu_init If one or more of the other CPU fails to call I S_cpu_init then the operation will fail after a pre defined timeout period For the valid set of flags bits please refer to the ics _cpu_init function 3 8182595 Rev 5 UM1112 Inter core system ICS API ICS_cpu_term Terminate the ICS system on a CPU Definition Arguments Returns Errors Context Description 3 include lt ics h gt void ICS cpu_term ICS _UINT flags flags Various flag bits which affect behavior None None Callable from task context only ICS _cpu_term will terminate the ICS system It should be called when a CPU is being shutdown and no longer requires the ICS system Calling it multiple times or when ICS_cpu_init has not been previously called will have no effect This function will terminate all tasks and release all resources associated with the local ICS system For example open ports and allocated regions will be closed and removed Currently no flags bits are defined and this parameter must be set to zero 8182595 Rev 5 163 224 Inter core system
194. ounter within a fixed time period This provides a fairly coarse grained level of monitoring that will detect CPU crashes However it will not detect errors where a software bug is causing no useful work or progression to be made Such levels of fault detection will be required to be implemented at a higher level such as in the MME system Table 20 Failure management functions Function name Description ICS watchdog _add Install a CPU watchdog handler ICS watchdog _remove Remove a previously installed watchdog handler ICS watchdog _reprime Re prime a triggered watchdog callback ICS _cpu_connect Connect to a CPU allowing ICS communication after a disconnect ICS_cpu_disconnect Disconnect ICS communication from a CPU ICS_watchdog_add installs a watchdog to monitor the operations of the set of CPUs defined by a CPU bitmask It defines a callback function to be called when a CPU in the monitored set stops operating The callback function for a watchdog has the prototype void ICS WATCHDOG CALLBACK ICS WATCHDOG handle ICS VOID param ICS _UINT cpuNum The callback function is supplied with a parameter defined in the wat chdog_add call the handle of the relevant watchdog and the CPU whose failure caused the watchdog to fire Once the callback has been triggered for a particular CPU it will not fire again until ICS watchdog _reprime has been called for that CPU Once failure of a CPU has been reported by a watchdog
195. plication see Section 2 6 Application and transformer specific data on page 27 The command code is used to uniquely identify a particular command in particular this identifier is used if ever a command must be aborted see Section 3 5 Aborting commands on page 42 Although the transformer specific parameter block held in the command s status structure should be filled in by the transformer the status structure itself must be treated by the transformer as read only All fields are updated automatically by MME If the command request is malformed in any way then this function should return an error code The following list though not exhaustive provides a few ways in which a command can be badly formed e Wrong number of input or output buffers e Incorrectly sized input or output buffers e Badly formed or incorrectly sized parameter block attached to the command request e Incorrectly sized parameter block attached to the command status MME CommandStatus t Itis not possible for the outgoing parameter block to be badly formed because they are assumed to be uninitialized data when MME ProcessCommand_t is called In systems where data buffers can be corrupted during transit transformers are required to gracefully handle badly formed input buffers It is possible to handle this by simply returning an error but this often makes it difficult for the application to handle failures For this reason it is usually preferable for a transformer to
196. r priorities The due time mechanism allows commands to be executed in a deterministic sequence However an application may require short duration transforms such as a series of audio frame decodes to complete while a lengthy transform operation such as a JPEG decode is being handled by another transformer instance To facilitate this MME supports five transformer priorities A priority is assigned to a transformer instance when the instance is created Transformer priorities are mapped onto the underlying operating system thread priorities an execution thread is created for each priority for which a transformer is instantiated 8182595 Rev 5 19 224 Using the MME API UM1112 2 2 2 3 20 224 Therefore a transform command executing on a high priority transformer instance takes precedence over a command executing on a lower priority transformer instance Commands at a particular priority are submitted sequentially to their transformer instances in due time order Structure size The MME API uses MME structures to pass data Typically there is a size field StructSize which must be set to the size of the structure in bytes see Section 4 2 MME constants enums and types on page 79 Summary of MME facilities The following is a summary of the main facilities provided by the MME API e MME initialization see Section 2 3 on page 20 MME provides API calls to allow the application to set up MME and to register transformers
197. rameter array For example enum SimpleIdx MME OFFSET AnInteger MME LENGTH Simple define MME TYPE AnInteger int i usage example l MME LENGTH Simple 3 7 3 Namespace management J The names of elements of all parameter arrays and their sub lists occupy a single shared namespace For this reason care must be taken to choose parameter names such that independent transformers do not interfere with each other This chapter provides guidelines on the selection of appropriate names Naming parameter arrays All parameter arrays must have a unique name To ensure this it is recommended to divide the name of the parameter into the following three components 1 A company or division name for example ST This divides the namespace and radically reduces the chance of namespace collision 2 Purpose or role of the transformer such as Ac3Decoder or Mixer 3 The operation to which this parameter list is targeted Table 5 Recommended postfixes for parameter array names contains guidance for standard MME operations 8182595 Rev 5 47 224 Writing an MME transformer UM1112 Table 5 Recommended postfixes for parameter array names Operation Postfix MME GetTransformerCapability Info Init or Global if the initialization parameters MME InitTransformer Are are not distinict MME SendCommand MME_SET_ GLOBAL TRANSFORM PARAMS and Global GlobalStatus reply MME SendCommand MME T
198. re delivered to the application by the callback mechanism Fields MME COMMAND COMPLETED EVT A command has been completed by MME The error code in MME_CommandStatus_t describes the state MME DATA UNDERFLOW EVT The transformer has run out of data before completing an output frame The error code in MME CommandStatus_t will be MME DATA UNDERFLOW MME NOT ENOUGH MEMORY EVT The transformer has insufficient output buffers to output a frame The error code in MME CommandStatus_t will be MME DATA OVERFLOW MME_TRANSFORMER_TIMEOUT The command has been timed out due to the CPU hosting the transformer crashing or failing to respond See also MME_Command_t MME_SendCommand 94 224 8182595 Rev 5 kyy UM1112 MME API MME_GenericCallback_t Definition Description Fields See also 3 include lt mme h gt Call mechanism for communication between transformer and host typedef void MME_GenericCallback t MME Event_t Event MME_Command_t CallbackData void UserData Generic callback mechanism for communication between transformer and host Guaranteed not to be called in a re entrant manner Event CallbackData UserData MME_SendCommand MME_InitTransformer Event associated with either data buffers or command transformations Pointer to the command structure related to this command Reference to user data provided with the call to MME _ InitTransformer 8182595 Rev 5 95 224 MME API UM
199. res passed by pointer is owned by the companion which may not be cache coherent with the host processor As such writes to any data structure are illegal and reads from output buffers should be avoided Fields StructSize CmdCode CmdEnd DueTime NumberInputBuffers NumberOutputBuffers DataBuffers p 3 Size of the structure in bytes Command to be performed Command mode completion Specify whether or not an event shall be generated when the command completes refer to MME_CommandEndType_t definition Time before the command has to be completed by the MME Number of read only buffers to be supplied to the transformer Number of read write buffers to be supplied to the transformer Note that overuse of output buffers leads to poor cache utilization due to excess cache purging Pointer to an array of pointers to data buffers containing all the input buffers followed by all the output buffers As such the length of the array is equal to or greater than NumberInputBuffers NumberOutputBuffers 8182595 Rev 5 81 224 MME API UM1112 See also 82 224 CmdStatus ParamSize Param_p MME_SendCommand MME_CommandCode_t MME_CommandEndType_t MME_Command Status_t MME_DataBuffer_t MME_GenericParams_t MME_Time_t MME_UINT 8182595 Rev 5 An MME _CommandStatus_t structure that will evolve during the processing of the command Fields of this structure will be filled by MME on either the host
200. ribed further in Section 3 4 2 Deferred commands on page 40 3 8182595 Rev 5 UM1112 Writing an MME transformer 3 2 Managing transformer lifetimes Two of the function pointers required by MME_RegisterTransformer are concerned with managing the lifetime of a transformer The transformer must implement the corresponding functions one is responsible for initializing a transformer instance while the other is responsible for terminating it This initialization function pointer is of type MME _InitTransformer t typedef MME ERROR MME InitTransformer t MME UINT initParamsLength MME GenericParams_t initParams void context The termination function pointer is of type MME_TermTransformer t typedef MME ERROR MME TermTransformer_t void context 3 2 1 Instantiation MME InitTransformer_t is called as a result of an application call to MME InitTransformer see Section 2 4 Managing transformer lifetimes on page 22 MME _InitTransformer_t is supplied with three parameters e a pointer to the transformer specific parameter block initParamsLength e the length of this block e context in which it must store a pointer to its state information If the transformer does not take any specific initialization parameters or the application neglected to provide them initParams is NULL and initParamsLength is zero If it is not possible to initialize a transformer instance either because the supplied parameters are incorrect or because there is no
201. rises Points to first valid byte in scattered buffer 8182595 Rev 5 89 224 MME API UM1112 MME_DataFormat_t Defines the data format of a transformer s I O Definition include lt mme h gt typedef struct unsigned char FourCC 4 MME DataFormat_t Description Used to define the format of the data a transformer supports for its input or output Refer to http www webartz com fourcc for a complete description of the FOURCC definition Fields FourCC Contains the format defined using its associated Four Character Code FOURCC 90 224 8182595 Rev 5 ky UM1112 MME API MME_DBG_FLAGS Describes properties of the debug logging flags Definition include lt mme h gt typedef enum mme_debug flags MME _DBG_ ERR 0x0001 MME _DBG_ INIT 0x0002 MME DBG MANAGER 0x0004 MME _DBG RECEIVER 0x0010 MME _DBG TRANSFORMER 0x0020 MME _DBG EXEC 0x0040 MME_DBG_ COMMAND 0x0100 MME_DBG BUFFER 0x0200 MME DBG FLAGS Description MME debugging flags specified as a bitmask value The valid set of debugging flags are detailed in Table 8 Table 8 MME debug logging flags Debug flag Description MME DBG ERR Log all error messages MME DBG INIT Log all initialization actions MME DBG MANAGER Log all MME administration actions MME DBG RECEIVER Log all transformer receiver actions ME DBG TRANSFORMER Log all client side transformer actions ME DBG EXEC Log all
202. rm request was responsible for filling it Should such information be required it is possible for transformer specific command status structures to be filled in by the transformer Altering global parameters Global parameters form part of each instantiated transformer and are manipulated using the MME SET GLOBAL TRANSFORM PARAMS command code Examples of global parameters include the chosen output format for data gain for each channel of a mixer or the magnitude of reverb effects Global parameters can also be used to change less obvious items of global transformer state For example the transformer could be directed to move any command in the deferred state to the MME_COMMAND_ FAILED state By effectively abandoning any commands it has deferred it will then be possible for a transformer instance to be terminated When altering the global parameters no data buffers are passed into or out of the transformer All information required by the transformer should be passed using the 8182595 Rev 5 ky UM1112 Using the MME API 2 10 2 10 1 2 10 2 3 transformer specific command parameters Similarly any information returned by the transformer should be contained in the transformer specific command status parameters Common types of transformer This section distinguishes between types of transformer based on how the input and output buffers are managed in order to discuss the advantages and disadvantages of each approach
203. rns Errors Context Description See also 132 224 Query the logical CPU number include lt ics h gt ICS_INT ics _cpu_self void None The logical ICS CPU number of the calling CPU Returns 1 if there was an error Callable from task and interrupt context Can be called before IcS_cpu_init Returns the logical CPU number of the calling CPU This information is determined by querying the BSP Registry of the running system An ICS system is made up of one or more logical CPUs numbered 0 to N 1 where N is the total number of CPUs in the system It is assumed that there is always a master CPU whose logical CPU number is 0 ics_cpu_lookup for details of the ICS logical CPU numbering system 3 8182595 Rev 5 UM1112 Inter core system ICS API ics_cpu_start Start execution of a CPU Definition include lt ics h gt ICS_ERROR ics cpu_start ICS OFFSET entryAddr ICS_UINT cpuNum ICS UINT flags Arguments ent ryAddr CPU execution start address cpuNum Logical CPU number of CPU being started flags Various flag bits which affect behavior Returns ICS SUCCESS CPU start was issued successfully Errors ICS INVALID ARGUMENT An invalid argument was supplied Context Callable from task and interrupt context Can be called before IcS_cpu_init Description ics cpu_start causes the logical CPU cpuNum to be started with execution 3 beginning at the supplied address This is an asynchronous
204. rocessors of mixed endianness The way MME handles mixed endian machines implies that the parameter block should be implemented as an array of 64 bit entities MME provides a number of macros that can be used to assist the transformer and application author to access data contained in such an array in a convenient but endian neutral manner These macros use a combination of constants and C preprocessor string concatenation in order to provide access both named and typed to elements of the parameter array Existing transformers and their applications may continue to pass parameters as a sequence of bytes instead of an array of 64 bit entities This is typically achieved by mapping a C structure as a parameter block This approach is not portable since it relies upon matching compiler behavior and endianness on all processors It is not recommended that new transformers pass their parameters in this manner Data representation The macros provided by MME to store data into an array of 64 bit entities use a specific data representation This representation allows 8 16 32 and 64 bit two s complement integers to be directly written by the CPU without any manipulation Similarly IEEE floating point numbers are typically stored using their normal bit pattern Table 4 shows the same parameter array elements represented in both big endian and little endian formats The MME implementation will automatically convert between these forms when a parame
205. rrors Context Description 174 224 include lt ics h gt typedef struct ics_msg desc ICS OFFSET data ICS SIZE size ICS MEM FLAGS mflags ICS _UINT srcCpu ICS CHAR payload ICS MSG INLINE DATA ICS_MSG_ DESC ICS_ERROR ICS _ msg recv ICS PORT port ICS MSG DESC rdesc ICS _LONG timeout port Port handle rdesc Receive descriptor pointer timeout Time in milliseconds to block waiting for a message ICS SUCCESS Successfully received a message rdesc Updated message descriptor on success ICS NOT INITIALISED ICS not initialized ICS INVALID ARGUMENT An invalid argument was supplied ICS HANDLE INVALID An invalid port handle was supplied ICS PORT CLOSED Port has been closed ICS _ENOMEM Failed memory resource allocation ICS_SYSTEM_ERROR A system error occurred ICS SYSTEM TIMEOUT Receive timed out Callable from task context only ICS _msg_recv blocks on the supplied port handle awaiting a new message arrival Messages are received in strictly the order they were sent to the port port should be a valid local open port as created with ICS port _alloc rdesc should be a pointer to a unique ICS_MSG_DESC sized region of memory timeout is the amount of time in milliseconds before the blocking wait should abort and return ICS SYSTEM TIMEOUT On successful completion the supplied rdesc descriptor will have been updated with all the new message information and any inline data The rdesc
206. ry handling on page 42 to indicate to the application that they have have exhausted either input or output buffers respecitvely commandInfo is the pointer originally supplied to the processing function while the error code is the value that the implementation will store in the error field of the command status prior to making any callbacks It is not safe to call MME_NotifyHost from an interrupt handler Deferred commands Deferred commands provide a means for a transformer to delegate some or all of its functionality to an asynchronous processing device such as a hardware accelerator A transformer indicates that it has deferred a command through a special error code MME TRANSFORM DEFERRED This return code indicates to MME that the command has not completed but that no further processing can be performed by the processor Since the command has not completed no callback will take place on the host after the processing function returns MME_TRANSFORM_ DEFERRED The host can be notified explicitly by the transformer code through calls to MME_NotifyHost described in MME_NotifyHost on page 67 Before returning MME_TRANSFORM_ DEFERRED the transformer must ensure the command will complete at some point in the future This is achieved by carrying out the following actions e Remember the MME Command _t pointer passed into the processing function This pointer is required when the time comes to notify the host processor that processing is
207. ry to be accessible by all CPUs and facilitating zero copy message passing between the CPUs A memory region must be aligned on an ICS page size boundary and the size must be a multiple of the ICS page size ICS_PAGE_SIZE Table 17 Memory region mapping functions Function name Description IcS_region_add Add a region to the local and remote CPU region tables ICS _region_remove Remove a region from the local and remote CPU region tables ICS region _virt2phys Translate a local virtual address into a physical one ICS region _phys2virt Translate a physical memory region address into a virtual address ICS region_add registers and maps a memory region in both the local CPU and the remote CPUs Given a virtual address physical address size some memory attributes supplied as flags and a set of CPUs defined in a bitmask it sets up the region and also returns a region handle which can later be used to remove the region by ICS _region_remove ICS region virt2phys translates a local CPU virtual address into a physical address and ICS region phys2virt translates a physical address in a defined region into a local CPU virtual address by making use of the region tables created Once a memory region has been registered addresses within that region can be used in calls to ICS_msg_send to allow a message to be sent using zero copy techniques This effectively transfers ownership of the buffer passed to ICS_msg_send to the re
208. s 0 00 0 eee 149 6 3 Macro definitions 0 0 00 cee 200 Appendix A ICS board support package 00 eee ee eee eee 201 A 1 Introduction 0 2 0 201 A 1 1 External BSP location 0 200000 cee eee ee 202 A 2 BSP data structures 0 0 0 0 ees 202 4 224 8182595 Rev 5 ky UM1112 Contents A 2 1 CPU table cadena dd Gace dade se ea Vo ae eee Cae ed a 202 A 2 2 Mailbox table cen sees oy ek heeled DHA eee Cha ee aa lt 203 A 2 3 Reset and boot addresses 0000 cece eee eens 203 A 2 4 CPU core name 00 00 cece eee 205 A 3 Example BSP template 2200000 0c eee ee eee 206 A 3 1 CPU Table aia iaei a a dango ead ad ne Mey dad beeen eee 206 A 3 2 Mailbox tables naana 0 0000 eee 207 A 3 3 Reset and boot addresses 000 cece eee ee 209 A 3 4 CPU core NaMe acho ag oN wks a ace ie oe he ea eA ache 210 Appendix B MME supplement 2 0 0c eee eee eee eee 211 B 1 Parameter encoding a cgi ae nnsa weak g Ream waa ee eke mde peo ken 211 B 1 1 Samples definitions 0 0 020000 c cee eee 211 Appendix C Advanced build options 002 cee eee es 216 C 1 Debugging assertions and logging 0 e eee eee 216 C 2 Tuneable parameters 00 0c cece 217 Appendix D ICS Linux module parameters 0000 eee eee 218 D 1 Support for declaring ICS regions on the module l
209. s have also called ics cpu_init If one or more of the other CPU fails to call ics _cpu_init then the operation fails after a pre defined timeout period Setting the flag bit value ICS_INIT_WATCHDOG causes the ICS system to monitor all the CPUs in the bitmask If any one of them fails an automatic callback is triggered on the local CPU which in turn disconnects the failed CPU from further communication See also ICS_cpu_init 3 8182595 Rev 5 127 224 Inter core system ICS API UM1112 ics_cpu_lookup Definition Arguments Returns Errors Context Description See also 128 224 Query the BSP Registry for CPU number include lt ics h gt int ics _cpu_lookup const ICS CHAR cpuName cpuName Name of CPU being queried A logical CPU number if one is found 1 CPU name not found Callable from task and interrupt context Can be called before ICcS_cpu_init ics cpu_lookup provides a mechanism for converting the symbollic names of the CPUs for example audio video into their logical ICS CPU numbers An ICS system is made up of one or more logical CPUs It is assumed that there is always a master CPU whose logical CPU number is 0 It is also assumed that the ICS master CPU will be always booted before the others and that it will always be running cpuName should be a 0 terminated ASCII string Examples of BSP Registry tables are given in Table 23 and Table
210. s to define a fixed size parameter block that contains the actual size the parameter block is required to be and use this to tell the application how much memory to allocate 8182595 Rev 5 ky UM1112 Writing an MME transformer 3 The following example shows part of the header file for a transformer that requires a capability structure of varied size enum STExampleInfoSize MME OFFSET STExampleInfoSize StructSize MME LENGTH STExampleInfoSize define MME TYPE STExampleInfoSize StructSize U32 typedef MME GENERIC64 STExampleInfoSize t MME LENGTH STExampleInfoSize enum STExampleInfo can not typedef STExampleInfo since it is of variable size The above transformer would be queried from application code in the following way MME ERROR err MME TransformerCapability_t capability STExampleInfoSize t query MME GENERIC64 info capability StructSize sizeof MME TransformerCapability t capability TransformerInfoSize sizeof STExampleInfoSize t j capability TransformerInfo p amp query err MME GetTransformerCapability STExample amp capability check for errors capability TransformerInfoSize MME PARAM query STExampleInfoSize Structsize info malloc capability TransformerInfoSize capability TransformerInfo p info err MME GetTransformerCapability STExample amp capability check for errors 8182595 Rev 5 37 224 Writing an MME
211. sc 84 ICS_msg_post nanana 117 118 172 MME _Commandld t in aaaea 85 ICS_msg_recv 117 118 174 MME_CommandState_t hehe ete Hate sh ae 86 ICS_msg_send 117 118 176 MME _CommandStatus t 27 38 87 ICS_msg_test PEET Swe se ee eae Bs Oe 1 18 178 MME_DataBuffer_t Ga eens abe ieee 23 89 ICS_msg_wait see 118 179 MME_DataFormatt 00 90 ICS_nsrv_add SPEED Coe eae Re ake 122 180 MME DBG FLAGS MEEO 91 ICS_nsrv_lookup 122 181 MME_DebugFlags ONENA ER 12 13 53 ICS_nsrv_remove 122 183 MME_DeregisterMemory 54 ICS_port_alloc 117 118 184 MME_DeregisterTransformer 55 ICS_PORT_CALLBACK 186 MME_ERROR 0000000 eeee ees 92 IS BONGO andes saranda aaa or 117 187 MME ErrorStr ccc coie nese sekscatase 56 ICS port free viva wiadant een 117 118 TOS MME Event t saan anid wi xitinrncdesterarsns 94 IGS port lookup 2 0 606 117 118 189 MME_FreeDataBuffer 24 57 ICS_region_add 119 190 MME GenericCallback t 00 95 ICS_region_phys2virt Se re ee 119 192 MME _GenericParams t 27 44 96 ICS_region_remove 119 193 MME_GetTransformerCapability 23 58 ICS_region_virt2phys 119 194 MME_GetTransformerCapability t 36 43 97 ICS_VERSION 2 0000005 200 MME_INDEXED P
212. scription Deregister a memory region that was previously registered with MME RegisterMemory specific transformer Comments Call type blocking function call See also MME_RegisterMemory 3 54 224 8182595 Rev 5 UM1112 MME API MME_DeregisterTransformer Deregister transformer Definition include lt mme h gt MME ERROR MME DeregisterTransformer const char name Arguments name The name of a transformer that has been registered with MME RegisterTransformer Returns MME SUCCESS The transformer has been successfully deregistered MME INVALID ARGUMENT The transformer name is not registered MME DRIVER_NOT INITIALIZED The MME driver has not been initialized Description Deregister a transformer that was previously registered on the CPU from which the call is made Comments Call type blocking function call See also MME_RegisterTransformer 3 MME _IsTransformerRegistered Section 2 3 3 Example on page 21 8182595 Rev 5 55 224 MME API UM1112 MME_ErrorStr Returns an MME error string Definition include lt mme h gt const char MME ErrorStr MME ERROR err Arguments err An MME_ERROR error code Returns A pointer to the corresponding MME error string Errors None Context Callable from task and interrupt context Can be called before MME_Init Description MME ErrorStr returns a pointer to the corresponding MME error string based on 56 224 the supplied err code This function is a useful way to
213. self on page 132 Updated the description of ics_cpu_start on page 133 Updated the definition and description of ics_load_elf_file on page 147 and ics_load_elf_image on page 148 Updated Context for CS_channel_send on page 157 Updated the description of CS_cpu_disconnect on page 160 Updated the description of CS_cpu_init on page 162 Updated the description of CS_msg_send on page 176 Introduction to Appendix A ICS board support package on page 207 rewritten and example updated Updated num in Table Note The order of the CPU definitions in this table must match that used in the CPU boot and reset tables in reset c on page 202 Updated Reset address on page 204 Updated Section A 3 1 CPU table on page 206 Updated Section A 3 2 Mailbox tables on page 207 Updated Section A 3 3 Reset and boot addresses on page 209 Updated Section C 1 Debugging assertions and logging on page 216 Added Appendix D ICS Linux module parameters on page 218 19 Oct 2009 A Initial release 220 224 8182595 Rev 5 ky UM1112 Index Index Symbols MME esi it 8G Gert awed bade eeG a ae 40 TREO oats bad evn ase e a se sneyaeae aanes ea Ta B E Backus Naur Form 0 6 Sant To a eR Fo Fe 11 Boot address 2020000 eee 204 MME 44 BSP configuration 00 eee 201 Example a ORI CORO ORR A i CRO bsp _boot_address reg 204 MME 48 bsp _cpu_count 203200 es pee ee eee bsp_cpu_
214. ssages are received strictly in the order they were sent to the port and asynchronous receives are processed in order too On successful completion the supplied rdesc descriptor will have been posted against the requested port This receive descriptor will be associated with the returned handle in eventp This handle can then be used in calls to ICS msg test andICS msg wait to test for or block for message arrival Until IcS_msg_wait has been called successfully on the returned eventp handle the memory associated with the rdesc parameter must not be reused or freed 8182595 Rev 5 ky UM1112 Inter core system ICS API For asynchronous posted receives new incoming messages will always be matched to the posted receive descriptors in the order that the receives were issued This also holds true if a blocking ICS_msg_recv is subsequently issued against the same port If the port associated with the asynchronous receive is closed by ICS_port_free then all outstanding posted receives will be signalled and completed with an ICS PORT CLOSED error port should be a valid local port as created with ICS_port_alloc rdesc should be a pointer to a unique ICS_MSG_DESC sized region of memory eventp should be a pointer to an ICS_MSG_ EVENT object 3 8182595 Rev 5 173 224 Inter core system ICS API UM1112 ICS_msg_recv Blocking call to receive a message on an ICS port Definition Arguments Returns E
215. ssize flags channelp ICS SUCCESS channelp ICS NOT INITIALISED ICS INVALID ARGUMENT ICS ENOMEM ICS SYSTEM ERROR Callable from task context only ICS ERROR ICS channel alloc ICS CHANNEL CALLBACK callback Callback handler function to be associated with this channel Handle to be supplied to the callback function Optional base memory address of channel Number of slots in the channel FIFO Slot size in bytes of each FIFO slot Various flag bits which affect behavior Channel handle pointer used to return allocated handle Successfully allocated channel Contains allocated channel handle ICS is not initialized An invalid argument was supplied Failed memory resource allocation A system error occurred 8182595 Rev 5 149 224 Inter core system ICS API UM1112 Description 150 224 ICS channel _alloc allocates a uni directional inter cpu communication channel on the local CPU Channels are formed as uni directional fixed length FIFOs These channels can then be used to send arbitrary byte formatted data between the CPUs All data successfully inserted into a channel is guaranteed to be delivered to the target CPU in the order is was sent The channel API provides the lowest overhead communication system between the ICS CPUs As such it provides a very raw interface with no protocol being added by ICS Programmers can use either interrupt or polling techniques to receive data through the ch
216. t an MPEG transformer has to process Parameters used by an MPEG transformer to pre reer Parama E decode an MPEG picture MPGV_PictureType_t Definition typedef enum MPGV_PICTURE_TYPE I MPGV_PICTURE_TYPE_P MPGV_PICTURE_TYPE B MPGV_PictureType t Description Defines the different picture types an MPEG video transformation can handle Fields MPGV_PICTURE_TYPE_ Picture type is I MPGV_PICTURE_TYPE_P Picture type is P MPGV_PICTURE_TYPE_B Picture type is B See also MPGV_DecodeParams_t 3 8182595 Rev 5 211 224 MME supplement UM1112 MPGV_GlobalParams_t Definition enum MPGV_GlobalParamsIdx MME OFFSET MPGVGlobal_ horizontal size value MME OFFSET MPGVGlobal_vertical_size value MME OFFSET MPGVGlobal_intra_quantiser_ matrix MME OFFSET MPGVGlobal_non_intra_quantiser matrix MME OFFSET MPGVGlobal_intra_quantiser_matrix 64 MME LENGTH MPGVGlobal MME OFFSET MPGVGlobal_non_intra_quantiser_ matrix 64 define MME TYPE MPGVGlobal_horizontal_size value U32 define MME TYPE MPGVGlobal_vertial_size value U32 define MME TYPE MPGVGlobal_intra_quantiser_ matrix U8 define MME TYPE MPGVGlobal_non_intra_quantiser matrix U8 typedef MME GenericParams_t MPGV_GlobalParams_t MME LENGTH MPGVGlobal Description Parameters to be used for the next transformation an MPEG transformer has to process The following code provides a simplified example MPGV_GlobalParams_t params MME PARAM params L
217. t data buffers e NumberOutputBuffers the number of output data buffers e DataBuffers p apointer to an array of pointers to the input buffers and output buffers The input buffer pointers must precede the output buffer pointers in this array e Param pand ParamSize with command specific parameters These should be set to NULL and zero respectively if there are no parameters See Section 2 6 Application and transformer specific data on page 27 and Section 3 7 Parameter passing on page 44 The state is held in the MME_CommandStatus_t structure within the MME_Command_t structure The command changes from state to state as shown in Figure 6 on page 28 8182595 Rev 5 27 224 Using the MME API UM1112 Note 28 224 Figure 6 Command state diagram Start state Submit command one comn rons Command de queued ne commo secure Command deferred Deferred state Command failed MME_COMMAND_FAILED Command succeeded pomno core Y Stop state When a command is issued it will be in the MME_COMMAND_ PENDING state for as long as it is enqueued waiting for processing time to become available The command s transition to the MME_COMMAND_EXECUTING state occurs when it is allocated processor time When a command is scheduled for execution on a companion processor it is not possible to distinguish between the MME_COMMAND_ PENDING and MME COMMAND EXECUTING st
218. t supplying the associated port handle param and an ICS MSG DESC message descriptor pointer If callbacks are not required then these parameters can be set to NULL ndesc determines the depth of the message queue associated with this port It must be a power of 2 in size Messages are stored on this queue in FIFO order until received by calling ICS_msg_ recv or ICS msg _ post A value of zero for this parameter is also allowed in which case messages will be held in the inter CPU FIFOs until a corresponding message receive is posted Note Setting the port message queue depth to zero should be used with caution as it could block all other messages in the inter CPU FIFO Currently no flags bits are defined and this parameter must be set to zero portp should be a pointer to an ICS_PORT object in which the allocated port handle will be returned on successful completion 3 8182595 Rev 5 185 224 Inter core system ICS API UM1112 ICS_PORT_CALLBACK Port callback function Definition Arguments Returns Errors Context Description 186 224 include lt ics h gt typedef ICS ERROR ICS PORT CALLBACK ICS PORT port ICS_VOID param ICS MSG DESC rdesc port The associated port handle param param argument as supplied to the port create function rdesc Receive descriptor pointer ICS SUCCESS Successfully processed message ICS FULL Failed to consume message Called from interrupt context only
219. ted Description Modify tuneable system wide configuration values MME uses sensible default values 3 for parameters such as thread priority however some users need to tune such values to optimize thread interactions Many values have been made tuneable to allow users to modify their systems without recompiling MME This call alters a single tuneable parameter selected by key which can be one of the values in Table 7 Table 7 Tuneable values for MME parameters Value Description Modify the default size of the MME data MME TUNEABLE BUFFER POOL SIZE buffer pool as used by MME _AllocDataBuffer Tune the priority of the MME manager thread This thread is responsible for administrative operations such as responding to MME TUNEABLE MANAGER THREAD MME GetTransformerCapability and PRIORITY E 7 7 MME InitTransformer This should have a high priority to prevent background batch processes such as audio encode from interfering with transformer creation Timeout period in milliseconds before a MME TUNEABLE TRANSFORMER_TIMEOUT transformer administration operation returns an error Tune the priority of the MME transformer thread This thread is responsible for receiving MME _SEND BUFFERS commands together with requests to abort the current function or terminate the transformer This should have a priority greater than or equal to the highest execution loop priority MME TUNEABLE TRANSFORMER THREAD _ PRIORITY
220. ter block is copied between processors of differing endianness 3 8182595 Rev 5 UM1112 Writing an MME transformer Table 4 Data representation endianness Size Little endian Big endian 8 bit O77 0 16 bit Ol 2 E 1 0 32 bit OQ 42 3a a aa fe BS 2 64 bit 01234567 76543210 The macros are aware of the size of the object they are storing allowing the base address of the big endian values to be automatically calculated at compile time 3 7 2 Mapping application data structures into MME parameters Three forms of parameter are managed by MME to support mapping of application data structures to MME parameters These are individual array and parameter array They are used to pass individual data elements arrays of elements and structures within structures respectively The following structure is used as an example struct MyParams unsigned char FooBar UINT32 TeePipes 10 struct MySubList char a E E The field FooBar is passed as an individual parameter the array TeePipes as an array parameter and the structure MySubList as a parameter array The descriptions in Section through to Section use enumerated constants to specify the offset of each entry within the MME array of 64 bit parameters The name of an entry in an enumeration is prefixed with MME_OFFSET_ for example MME_OFFSET_FooBar The type of an entry is defined with a define directive and prefixed with MME_TYPE_ for exampl
221. the channel it defines a callback handler function for the channel the FIFO length and slot size and optionally the memory base for the FIFO data The callback function is to be invoked in interrupt context whenever a new entry arrives in the FIFO and may be NULL if a process based approach to receiving is wanted In order to send using an ICS channel it must first be opened ICS_ channel open opens a channel for sending and returns a handle to be used for send operations Opening a channel is only necessary for the sender the receiver implies opening by the allocation The channel handle may be one opened locally by ICS_channel_alloc by looking up a channel object in the name server see Section 5 6 Name server on page 122 or one passed to the sender by some other mechanism ICS _channel_send sends a buffer to a channel using a send channel handle The buffer is processed by either e invoking the callback function at the receiver or if no callback function is defined the receiver calling an ICS_channel_recv function on returning from the function a pointer to the buffer is supplied so that the receiving application can process it ICS_channel_ send will return an error if there is no free slot in the FIFO The callback function associated with a channel has prototype ICS ERROR ICS CHANNEL CALLBACK ICS CHANNEL channel ICS VOID param void buf The callback function is supplied with the channel handle a parameter d
222. tion pointers required by MME RegisterTransformer The specification of each of these functions is described in this chapter Table 3 Transformer function pointers Function pointer type Description MME AbortCommand_t Transformer API function to abort a command iS a Transformer API function to return a transformer MME GetTransformerCapability t as capability MME InitTransformer_t Transformer API function to initialize a transformer MME ProcessCommand_t Transformer API function to process a command MME TermTransformer_t Transformer API function to terminate a transformer In addition to providing the five functions all but the most basic transformer will require parameters to control how it processes data The parametric information is typically defined in a transformer specific header file included by both the application and the transformer code Detailed information on passing parameters in a portable endian neutral manner is discussed in Section 3 7 on page 44 The process for writing a transformer is identical whether you are targeting the host or a companion processor although obviously where the host and companion have different CPU architectures then optimization decisions such as data buffer management may have to be revisited Transformers that utilize a hardware accelerator require only a small amount of extra complexity in the MME interface to manage asynchronous processing This is desc
223. transformer UM1112 3 4 Note Note 38 224 Processing a command The transformer must implement a function that supports the processing any of the three types of commands introduces in Section 2 8 Fault detection and recovery on page 29 The function must be compatible with the function pointer type MME ProcessCommand_t which is an argument of MME_RegisterTransformer typedef MME ERROR MME ProcessCommand t void context MME Command_t commandInfo MME _ProcessCommand_t is called as a result of an application call to MME SendCommand see Section 2 7 Issuing commands on page 27 This function is supplied with the context pointer described in Section 3 2 Managing transformer lifetimes on page 35 It is also supplied with the command structure commandInfo describing the actions requested of the transformer The command structure consists of two parts the incoming command request and the outgoing command status The command request portion is filled in by the application before calling MME _SendCommand and contains incoming parameters and any data buffers relevant to the command MME _Command_t contains a status structure MME_CommandStatus_t that is updated by MME before and after calling MME _ProcessCommand_t During processing only the status structure parameter block and command identifier contain useful values The parameter block is filled in by the transformer in order to pass back state information to the ap
224. y reach oxfff ffff and overflow For this reason when due times are compared it is not a simple magnitude comparison Instead the times are arranged such that tafter tbefore is less than Ox7fffffff Figure 4 shows what this comparison means in practice by showing how t will be compared against all possible 32 bit values 8182595 Rev 5 ky UM1112 Using the MME API 3 Figure 4 Time arithmetic x ticks Past Future Before Now y ticks O0 OxFFFF FFFF When due times are exactly equal then the least recently issued command will be executed first This permits commands to be executed in strict FIFO order if their due times are always the same value zero is a good candidate value in this case although any value can be used There are three obvious ways an application may choose to utilize the due time e As constant value across all transformers This results in FIFO scheduling within a transformer and round robin scheduling among transformers e As unique constant values This results in FIFO scheduling within a transformer and prioritized scheduling among transformers This differs from normal prioritized scheduling because low priority transforms will not be pre empted This may yield slightly better utilization of processor bandwidth at the expense of latency e Astrue due time This results in due time scheduling within all commands irrespective of which transformer queue they appear on Transforme

UM1112 User manual - FTP Directory Listing

Contents

Download Pdf Manuals

Related Search

Related Contents