diff options
Diffstat (limited to 'pcilib/py.h')
| -rw-r--r-- | pcilib/py.h | 122 |
1 files changed, 98 insertions, 24 deletions
diff --git a/pcilib/py.h b/pcilib/py.h index 04b4e8b..c372a09 100644 --- a/pcilib/py.h +++ b/pcilib/py.h @@ -1,7 +1,10 @@ #ifndef _PCILIB_PY_H #define _PCILIB_PY_H -#include "pcilib.h" +#include <pcilib.h> +#include <pcilib/error.h> + +#define pcilib_python_error(...) pcilib_log_python_error(__FILE__, __LINE__, PCILIB_LOG_DEFAULT, PCILIB_LOG_ERROR, __VA_ARGS__) typedef struct pcilib_py_s pcilib_py_t; typedef void pcilib_py_object; @@ -10,39 +13,110 @@ typedef void pcilib_py_object; extern "C" { #endif +void pcilib_log_python_error(const char *file, int line, pcilib_log_flags_t flags, pcilib_log_priority_t prio, const char *msg, ...); + +/** Initializes Python engine + * + * This function will return success if Python support is disabled. Only functions + * executing python call, like pcilib_py_eval_string(), return errors. Either way, + * no script directories are configured. The pcilib_add_script_dir() call is used + * for this purpose. + * + * @param[in,out] ctx - pcilib context + * @return - error or 0 on success + */ int pcilib_init_py(pcilib_t *ctx); -int pcilib_py_add_script_dir(pcilib_t *ctx); -int pcilib_py_eval_string(pcilib_t *ctx, const char *codestr, pcilib_value_t *value); + +/** Cleans up memory used by various python structures + * and finalyzes python environment if pcilib is not started from python script + * + * @param[in] ctx - the pcilib_t context + */ void pcilib_free_py(pcilib_t *ctx); +/** Add an additional path to look for python scripts + * + * The default location for python files is /usr/local/share/pcilib/models/@b{model}. + * This can be altered using CMake PCILIB_MODEL_DIR variable while building or using + * PCILIB_MODEL_DIR environmental variable dynamicly. The default location is added + * with @b{location} = NULL. Additional directories can be added as well either + * by specifying relative path from the default directory or absolute path in the + * system. + * + * @param[in,out] ctx - pcilib context + * @param[in] location - NULL or path to additional scripts + * @return - error or 0 on success + */ +int pcilib_py_add_script_dir(pcilib_t *ctx, const char *location); + +/** Loads the specified python script + * + * Once loaded the script is available until pcilib context is destryoed. + * + * @param[in,out] ctx - pcilib context + * @param[in] name - script name, the passed variable is referenced and, hence, should have static duration + * @return - error or 0 on success + */ +int pcilib_py_load_script(pcilib_t *ctx, const char *name); + +/** Check if the specified script can be used as transform view and detects transform configuration + * + * @param[in,out] ctx - pcilib context + * @param[in] name - script name + * @param[out] mode - supported access mode (read/write/read-write) + * @return - error or 0 on success + */ +int pcilib_py_get_transform_script_properties(pcilib_t *ctx, const char *name, pcilib_access_mode_t *mode); -int pcilib_py_init_script(pcilib_t *ctx, const char* module_name); -int pcilib_py_free_script(pcilib_t *ctx, const char* module_name); -int pcilib_script_run_func(pcilib_t *ctx, const char* module_name, - const char* func_name, pcilib_value_t *val); - -int pcilib_py_get_transform_script_properties(pcilib_t *ctx, - const char* module_name, - pcilib_access_mode_t *mode); +/** + * Get the PyObject from the polymorphic type. The returned value should be cleaned with Py_XDECREF() + * @param[in] ctx - pcilib context + * @param[in] val - initialized polymorphic value of arbitrary type + * @param[out] err - error code or 0 on sccuess + * @return - valid PyObject or NULL in the case of error + */ +pcilib_py_object *pcilib_get_value_as_pyobject(pcilib_t* ctx, pcilib_value_t *val, int *err); -/*! - * \brief Converts pcilib_value_t to PyObject. - * \param ctx pointer to pcilib_t context - * \param val pointer to pcilib_value_t to convert - * \return PyObject, containing value. NULL with error message, sended to errstream. +/** + * Initializes the polymorphic value from PyObject. If `val` already contains the value, cleans it first. + * Therefore, before first usage the value should be always initialized to 0. + * @param[in] ctx - pcilib context + * @param[in,out] val - initialized polymorphic value + * @param[in] pyval - valid PyObject* containing PyInt, PyFloat, or PyString + * @return - 0 on success or memory error */ -pcilib_py_object* pcilib_get_value_as_pyobject(pcilib_t* ctx, pcilib_value_t *val, int *err); +int pcilib_set_value_from_pyobject(pcilib_t* ctx, pcilib_value_t *val, pcilib_py_object *pyval); +/** Evaluates the specified python code and returns result in @b{val} + * + * The python code may include special variables which will be substituted by pcitool before executing Python interpreter + * @b{$value} - will be replaced by the current value of the @b{val} parameter + * @b{$reg} - will be replaced by the current value of the specified register @b{reg} + * @b{${/prop/temp}} - will be replaced by the current value of the specified property @b{/prop/temp} + * @b{${/prop/temp:C}} - will be replaced by the current value of the specified property @b{/prop/temp} in the given units -/*! - * \brief Converts PyObject to pcilib_value_t. - * \param ctx pcilib context - * \param pyVal python object, containing value - * \param val initialized polymorphic value - * \return 0 on success or memory error + * @param[in,out] ctx - pcilib context + * @param[in] codestr - python code to evaluate + * @param[in,out] val - Should contain the value which will be substituted in place of @b{$value} and on + * successful execution will contain the computed value + * @return - error or 0 on success */ -int pcilib_set_value_from_pyobject(pcilib_t* ctx, pcilib_value_t *val, pcilib_py_object* pyObjVal); +int pcilib_py_eval_string(pcilib_t *ctx, const char *codestr, pcilib_value_t *val); +/** Execute the specified function in the Python script which was loaded with pcilib_py_load_script() call + * + * The function is expected to accept two paramters. The first parameter is pcipywrap context and the @b{val} + * is passed as the second parameter. The return value of the script will be returned in the @b{val} as well. + * If function returns Py_None, the value of @b{val} will be unchanged. + * + * @param[in,out] ctx - pcilib context + * @param[in] script - script name + * @param[in] func - function name + * @param[in,out] val - Should contain the value of second parameter of the function before call and on + * successful return will contain the returned value + * @return - error or 0 on success + */ +int pcilib_py_eval_func(pcilib_t *ctx, const char *script, const char *func, pcilib_value_t *val); #ifdef __cplusplus } |