dacs_de_start

NAME

dacs_de_start - Start a process on a DE.

SYNOPSIS

DACS_ERR_T dacs_de_start ( de_id_t de, void *prog, char const **argv, char const **envv, DACS_PROC_CREATION_FLAG_T creation_flags, dacs_process_id_t *pid )

Call parameters
`de`	The target DE where the program will execute.
`*prog`	A pointer to the program text to execute. What this points to is platform-dependent, and also dependent on the `creation_flags` parameter.
`**argv`	A pointer to an array of pointers to argument strings (the argument list), terminated by a `NULL` pointer.
`**envv`	A pointer to an array of pointers to environment variable strings (the environment list), terminated by a `NULL` pointer.
`creation_flags`	An implementation-specific flag that specifies how the executable program is found. This can be any of: `DACS_PROC_LOCAL_FILE`: a fully qualified pathname, `DACS_PROC_LOCAL_FILE_LIST`: a list of fully qualified pathnames, `DACS_PROC_REMOTE_FILE`: a fully qualified path on a remote system, or `DACS_PROC_EMBEDDED`: the handle of an embedded executable image.

Return parameter
`*pid`	A pointer to a location where the process id is stored on successful return.

DESCRIPTION

The dacs_de_start service starts a process on the specified DE. The service can be called several times to start one or more processes on the same DE. The number of processes that can be started on a particular DE is platform and implementation dependent.

Note: In the execution environment, the environment variables in DACS_START_ENV_LIST will be a list appended to the environment variables in the list under parameter char const **envv.

Note: The use of duplicate environment variables across the lists in the dacs_de_start() service and DAC_START_ENV_LIST is possible. However the value that will be used is implementation dependent, because accessing environment variables is implementation dependent.

Note: Some implementations may prohibit one type of DE from starting processes on another DE. If this situation exists, the dacs_de_start() service returns DACS_ERR_PROHIBITED.

RETURN VALUE

The dacs_de_start service returns an error indicator defined as:

DACS_SUCCESS: normal return.
DACS_ERR_INVALID_ADDR: a pointer is invalid.
DACS_ERR_INVALID_ATTR: a flag or enumerated constant is invalid.
DACS_ERR_NO_RESOURCE: unable to allocate required resources.
DACS_ERR_PROHIBITED: the operation is prohibited by the implementation.
DACS_ERR_INVALID_DE: the specified DE is either invalid or not reserved.
DACS_ERR_INVALID_TARGET: the operation is not allowed for the target DE.
DACS_ERR_PROC_LIMIT: the maximum number of processes supported has been reached.
DACS_ERR_INVALID_PROG: the specified program could not be executed.
DACS_ERR_INVALID_ARGV: argv is too large or invalid.
DACS_ERR_INVALID_ENV: envv is too large or invalid.
DACS_ERR_DACSD_FAILURE: unable to communicate with DaCSd.
DACS_ERR_SYSTEM: a system error was encountered. This often indicates the executable file was not found on the remote system.

ENVIRONMENT

Hybrid DaCS has specific environment variables in the process issuing the dacs_de_start() call. This allows an external program such as a debugging or profiling tool to be started which in turn starts the accelerator process.

These variables are:

DACS_START_PARENT

specifies the command used to start an auxiliary program which starts the accelerator process. Within the command, %e , %a and %p are replaced respectively by the accelerator executable name, the accelerator arguments, and the parent's listening port value.

For example, given:

DACS_START_PARENT="/usr/bin/gdb --args %e %a"

then:

dacs_de_start (de, "myaccel", "myargs", 0, ppid)

would launch the command:

/usr/bin/gdb --args myaccel myargs

DACS_START_FILES

specifies the name of a file which contains a list of files to transfer to the PPE prior to launching the accelerator process. File names are fully-qualified POSIX-compliant pathname files.

DACS_START_ENV_LIST

specifies an additional list of environment variables for the initial program spawn on the accelerator. List items are separated by semicolons. An example of the format is:

ENV1=VAL1;ENV2=VAL2;QSHELL_*;ENV3

where:

ENV1 and ENV2 are the environment variables and VAL1 and VAL2 are their respective settings,
QSHELL_* means pull all environment variables prefixed with QSHELL_ from the present environment, and
ENV3 means pull the environment variable from the present environment and pass on.

Delete functions, such as <name>= and <prefix>*= to drop environment variables by name or prefix, are not supported in SDK 3.0.

DACS_PARENT_PORT

specifies the value of %p to pass in the dacs_de_start() call. This value is post-incremented in the environment so that it is one more on the next dacs_de_start() call.

Note: The port allocated by DACS_PARENT_PORT is solely the responsibility of the environment setter and is not guaranteed to be available on the accelerator OS.