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.

Link Arbiter Daemon

From Texas Instruments Wiki
Jump to: navigation, search
Software: Link Arbiter Daemon
Hardware supported ,|x|Supports hardware::x}}
Software environment(s) ,|x|Runs in software environment::x}}
Status Has status::Stable

Link Arbiter Daemon (LAD) Overview

This topic is an overview of an entity called the Link Arbiter Daemon (LAD). The LAD enables multiple Linux processes to share a same instance of codec server (i.e. DSP image) that is loaded onto the DSP on a heterogeneous platform (e.g. DM644x or OMAP3530). It is distributed with Codec Engine (CE).

Summary

  • LAD is used only to request DSP startup/shutdown; in between, applications can make direct calls to DSPLink’s communication APIs (such as MSGQ_get()).
  • LAD also requires an "agreed upon" DSP executable, and Link configuration, acceptable to all ARM-side apps that will concurrently share DSP.
  • LAD is provided as source, to enable integrator to define multiple LAD/Link configurations
  • It includes limited error checks, and a basic recovery mechanism to detect if a client app terminates without disconnecting first

Requirements

  • CE 1.20 or later
  • DSPLINK 1.40.05 P3 or later

Approach

The Link Arbiter Daemon (LAD) exists as a separate process. The driving requirement for this is Link's convention of "owner" of the DSP to be the first application to use it. To allow CE-based apps and other apps to come and go without ordering restrictions, neither of these apps can be the "owner", but an independent entity is required. (Note, the restriction of the "owner" process being the first to connect was lifted in later versions of DSP Link.)

The LAD is normally started before any application using DSP Link and/or Codec Engine are run.

LAD knows about pre-defined Link configurations, and can reference these by name in an array of LINKCFG_config structures.

Lad config2.jpg

At startup, LAD creates a FIFO (named pipe) for listening for connection requests from other user-mode clients. When a connection request comes in, LAD opens a dedicated FIFO for sending responses to the client.

Lad overview.jpg

In the case above, we have an application called AVME which comes along first and starts up the DSP, followed later by a CE-based application, that simply connects to the running DSP.

Wrappers to simplify client communication with LAD reside in a ladclients package. These wrappers abstract and isolate the underlying implementation for communication with LAD, and LAD itself.

Meanwhile, for a CE-based application, these wrappers will be seamlessly called by CE's internal modules (either the OSAL or IPC, depending on the version of CE); the application's runtime is exactly the same, regardless if LAD is used or not. The decision on whether or not to use LAD for the application is a "system" decision, made at application config time, specified via the app's config script (details below).

At run-time, LAD processes command in FIFO order, and these commands run to completion before the next command is accepted. This serialization eliminates race conditions, such as LAD being in the middle of starting the DSP at request of one client, when another client requests a start of the DSP with a different server image.

Daemon Command Line Usage

The lad daemon takes up to 2, optional command line arguments.

The first argument is the path to the log file, if you want one generated. If you don't specify a full path, the log file is placed into /tmp/LAD.

The second argument is the string "verbose" if you want verbose output.

Using LAD in a Codec-Engine-based application

No change to the C code in a Codec-Engine-based application is necessary. To use the LAD, add the following lines to the CE configuration script:

osalGlobal.useLinkArbiter = true;

The link configuration to be used is specified via a new engine configuration parameter, for example:

myEngine.linkCfg= "CE_default";

Note, the Codec Engine Examples include an example demonstrating the use of LAD.

The name assigned to linkCfg is matched against the names present in the LAD source file ladconfig.c in the Codec Engine location ti/dsplink/utils/lad. These names are contained in an array of Strings named configName. You must choose one of the names present in that array. Those names correspond to similarly named structures (e.g., name "user0" corresponds to structure user0_LINKCFG_Config) that are defined in similarly named source files that contain DSPLINK configuration objects (e.g., user0_LINKCFG_Config for use with a DM6446 is defined in the file user0_linkcfg_dm6446.c).

Since the shipped ladconfig.c contains references to 4 different DSPLINK configuration objects, the LAD executable can support loading codec servers that match any of those 4 different configurations, although only one codec server can be loaded at a time. The user is expected to modify LAD's DSPLINK configuration objects to match their codec server configuration, but keep in mind that one of those configurations as shipped in CE will likely match the "all_codecs" example codec server configuration.

After configuring the LAD, it is started as a separate Linux process before any DSPLINK-based application is run, by invoking the following commands:

echo export LAD environment variable to config source of server images
export LAD_SERVERPATH=`pwd`
echo Starting Link Arbiter Daemon using servers at $LAD_SERVERPATH
./lad.x470MV log.txt &

Trace Support

Codec Engine supplies a large amount of trace to assist in debugging and profiling. When LAD is configured into a system, there are potentially multiple processes involved, and as a result, there is ambiguity as to which process should be acquiring the DSP-side trace (since there can be more than one!). It's confusing if process A to gets trace from process B and vice-versa.

To disambiguate which process has the right to acquire the DSP-side trace, LAD-based systems can call Server_connectTrace() right after Engine_open(). This API tells Codec Engine that this process is entitled to acquire the DSP-side trace; if another process tried to Server_connectTrace(), the request would be rejected. Users should also call Server_disconnectTrace() when they want another process to be able to connect and gather trace.

LAD Commands (useful for non Codec-Engine based applications that use DSPLINK)

The following table lists LAD commands. Each command is invoked by the client, using the LAD client APIs.

LAD commands
LAD Command Wrapper Function Args Comments
CONNECT LAD_connect() LAD_ClientHandle * handle Establishes new LAD client connection. LAD opens up a dedicated output FIFO for sending responses to the client. LAD sends first response (to connect request) to the client wrappers via the FIFO, with its assigned client ID
STARTUPDSP LAD_startupDsp() handle, cpuID, linkConfigId, imageName If the DSP is not currently in use: does PROC_setup(), PROC_attach(), PROC_load(), POOL_open() (for all pools), PROC_start(), and MSGQ_transportOpen(). If DSP is in use, and same imageName requested, then returns an "already running" success code. If the DSP is in use, and different imageName requested, then returns "access denied".
RELEASEDSP LAD_releaseDsp() handle If DSP was previously started by this client: decrements reference count. If reference count not zero then returns "still running" success code. Else, calls MSGQ_TransportClose(), POOL_Close() (for all pools), PROC_Stop(), PROC_Detach(), PROC_Destroy() to release the DSP. Return success, or error code if teardown failed.
GETDSPSTATUS LAD_getDspStatus() handle If the handle corresponds to a current client connection: returns state of DSP. If DSP is started returns structure with: dsp state, linkConfigId, imageName, and # of clients who have successfully "started" the DSP.
DISCONNECT LAD_disconnect() handle Removes this client connection to LAD. LAD and wrappers close their ends of the dedicated response FIFO.

Limitations

Startup Before Any Clients

LAD needs to be explicitly started before any client applications try to connect to the DSP. LAD can be launched from a terminal shell by invoking the LAD executable, e.g., lad.x470MV, as described above.

Only Support Independent Processes

LAD supports multi-application use cases where client applications exist as independent processes. Situations where processes are related (parent, child, siblings) have not been tested.

Single Per-Process Connection to LAD

Applications are allowed only a single connection to LAD. Once successfully connected, if the application tries to open another simultaneous connection the request will be denied, and LAD_connect() will return LAD_ACCESSDENIED.

Maximum Number of Simultaneous Connections

The maximum number of simultaneous client connections to LAD is currently 16. Meaning, at most 16 client applications can be connected to LAD for DSP control at any given time.

Known Link Configurations

The maximum number of "known" Link configurations by LAD is currently four.

No Arguments to DSP's main()

When using LAD, no "command line" arguments can be passed to the DSP's main() routine.

The basis for this constraint is that multiple apps might want to pass different arguments to the DSP's main() routine. But when using LAD, only the app that is first to start the DSP would have its arguments interpreted by main(), and all other apps attempting start later would not have their arguments interpreted because main() will not run again until the DSP is shutdown. Therefore, to enforce consistency, LAD_startupDsp() does not accept any arguments, and no arguments will be used when starting up the DSP.