Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

SysLink ProcMgr Changes

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

The SysLink ProcMgr API has gone through some changes to address user feedback, some unfortunately breaking compatibility. This article describes those changes.

ProcMgr_MAX_MEMORY_REGIONS

In all SysLink 2.x releases to date, there is an upper limit on the maximum number of memory regions that can be mapped. These mapped regions can include hardware blocks SysLink needs to access, code/data sections in the loaded slave executable, and regions mapped dynamically using ProcMgr_map().

SysLink 2.00 and 2.10.00

In SysLink 2.00, this max number is specified at build time, via the ProcMgr_MAX_MEMORY_REGIONS definition in ti/syslink/ProcMgr.h. Users needing to map more regions than the default need to change this #define and rebuild SysLink and their applications.

The value of ProcMgr_MAX_MEMORY_REGIONS in SysLink 2.00 and 2.10.00 was 32.

SysLink 2.10.01

Feedback received after the 2.00 release indicated many users needed to map more regions than the default (32 in SysLink 2.00.* and 2.10.00), so the default was increased from 32 to 96 in the SysLink 2.10.01 release.

SysLink 2.10.02

After the 2.10.01.15 release, customers complained about compatibility breaks, which initially we were confused about. We changed (what we thought was) a purely internal #define which applications were not exposed to. However, we soon realized that some users were unfortunately exposed to this #define change, specifically if they used the ProcMgr_getProcInfo() API. This was because the struct passed to that service was sized based on this ProcMgr_MAX_MEMORY_REGIONS definition!

This basically meant customers (e.g. Codec Engine, etc) could not deliver a single library that would work across SysLink customers with different ProcMgr_MAX_MEMORY_REGIONS definitions. We needed to fix the ProcMgr_getProcInfo() API to be independent of the ProcMgr_MAX_MEMORY_REGIONS definition. This change was done in SysLink 2.10.02, details are further below.

Further, to ensure SysLink users were not accidentally exposed to future changes to the ProcMgr_MAX_MEMORY_REGIONS definition, the definition itself was moved from a public user header (ti/syslink/ProcMgr.h) to a SysLink internal header (ti/syslink/inc/knl/ProcDefs.h).

ProcMgr_getProcInfo()

SysLink 2.00.*, 2.10.00, and 2.10.01

In SysLink 2.00, the ProcMgr_getProcInfo() API was introduced. It returns a structure that, as described above, is unfortunately sized by the ProcMgr_MAX_MEMORY_REGIONS definition. As a result, any caller of this API is tightly bound to the value of ProcMgr_MAX_MEMORY_REGIONS as defined by their particular build of SysLink at compile time.

SysLink 2.10.02

To address this, SysLink 2.10.02 broke the binding between the ProcMgr_getProcInfo() API and the ProcMgr_MAX_MEMORY_REGIONS definition by changing the ProcInfo.memEntries[] array size from ProcMgr_MAX_MEMORY_REGIONS elements to zero elements - where the user must allocate enough space for the number of entries. Users can call the new API, ProcMgr_getMaxMemoryRegions() to help determine the number of elements the array must hold.

Unfortunately, this introduces an unavoidable compatibility break. Here is an example usage of ProcMgr_getProcInfo() before the change (versions < 2.10.02) and after (versions >= 2.10.02).

/* SysLink 2.10.01 and before.
 *
 * Though simpler, the size of ProcMgr_ProcInfo varies with
 * ProcMgr_MAX_MEMORY_REGIONS!
 */
ProcMgr_ProcInfo procInfo;
 
status = ProcMgr_getProcInfo(handle, &procInfo);
/* SysLink 2.10.02 and after
 *
 * Though more complex, the size of ProcMgr_ProcInfo is not tied to
 * ProcMgr_MAX_MEMORY_REGIONS.
 */
ProcMgr_ProcInfo *procInfo;
UInt32 maxMemoryRegions;
Int procInfoSize;
 
maxMemoryRegions = ProcMgr_getMaxMemoryRegions(handle);
procInfoSize = sizeof(ProcMgr_ProcInfo) +
        (maxMemoryRegions * sizeof(ProcMgr_MappedMemEntry));
procInfo = Memory_alloc(NULL, procInfoSize, 0, NULL);
 
status = ProcMgr_getProcInfo(handle, procInfo);