| Samsung Client API reference 1.0

- Main Page
- Related Pages
- Modules
- Files

Enumerations | Functions
Samsung Client API

## Enumerations
enum | Cluster { CLUSTER_BIG, CLUSTER_LITTLE, CLUSTER_DEFAULT, CLUSTER_MAX_VALUE }
enum | { DISABLE_CRYPTO_CLK, ENABLE_CRYPTO_CLK }
enum | ta_debug_service_type_t { TA_DEBUG_SERVICE_DLM, TA_DEBUG_SERVICE_PMR }

## Functions
const char * | get_error_name (TEEC_Result result)
| The function returns string representation of `TEEC_Result` type. More...
const char * | get_error_text (TEEC_Result result)
| The function returns description of `TEEC_Result` type. More...
const char * | get_return_origin (uint32_t returnOrigin)
| The function description of `origin` type. More...
TEEC_Result | TEECS_SetCluster (TEEC_Session *session, Cluster cluster)
| The function sets TA (main thread and its descendants, created after call) to desired cpu cluster. More...
TEEC_Result | TEECS_Boost (TEEC_Session *session)
| The function enables performance boosting for current TA session. More...
TEEC_Result | TEECS_Unboost (TEEC_Session *session)
| The function disables performance boosting for current TA session. More...
TEEC_Result | TEECS_SetCryptoClk (TEEC_Context *context, uint32_t state)
| The function switches crypto clocks ON/OFF Initially designed to reduce power consuption on Qualcomm chipsets A reference counter is maintained in TEEC_ContextImp. More...
TEEC_Result | TEECS_GetSessionId (const TEEC_Session *session, TEEC_UUID *session_id)
| Function gets session ID. More...
TEEC_Result | TEECS_OpenSession (TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, const void *ta_image, const size_t ta_image_size, uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin)
| The function opens TA which is located not exactly in /vendor/tee directory. Function behaves the same way as TEEC_OpenSession(), but provides two additional parameters. `ta_image` and `ta_image_size`. More...
TEEC_Result | TEECS_OpenSession1 (TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, const char *destination_path, uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin)
| The function opens TA which is located not exactly in /vendor/tee directory. Function behaves the same way as TEEC_OpenSession(), but provides one additional parameter. `destination_path` (e.g. /system/tee, /data/tee) wherever CA has appropriate permission. More...
TEEC_Result | TEECS_TADebugServiceCtl (ta_debug_service_type_t type, const TEEC_UUID *monitoredTA, const TEEC_UUID *monitoredSession)
| Create a request into underlying TEE implementation to provide TEE TA Debug functionality for current Client Application. More...
TEEC_Result | TEECS_WaitTADeath (TEEC_Session *session)
| Wait for unexpected death of TA. More...

## Detailed Description

## Enumeration Type Documentation

anonymous enum

`#include <tees_client_api.h>`

Crypto clocks enum

Enumerator
DISABLE_CRYPTO_CLK | Disable crypto clocks
ENABLE_CRYPTO_CLK | Enable crypto clocks

enum Cluster

`#include <tees_client_api.h>`

This is an cluster enum

enum ta_debug_service_type_t

`#include <tees_client_api.h>`

Debug service type enum for TEE TA Debug spec

Enumerator
TA_DEBUG_SERVICE_DLM | Debug log message type
TA_DEBUG_SERVICE_PMR | Post mortem report type

## Function Documentation

const char* get_error_name | ( | TEEC_Result | result | ) |

`#include <tees_client_api.h>`

The function returns string representation of `TEEC_Result` type.

Parameters

  [in] | result | the value to get representation.

Return values

  string | representation of `TEEC_Result`.

const char* get_error_text | ( | TEEC_Result | result | ) |

`#include <tees_client_api.h>`

The function returns description of `TEEC_Result` type.

Parameters

  [in] | result | the value to get description.

Return values

  string | description of `TEEC_Result`.

const char* get_return_origin | ( | uint32_t | returnOrigin | ) |

`#include <tees_client_api.h>`

The function description of `origin` type.

Parameters

  [in] | returnOrigin | the value to get description.

Return values

  string | description of `origin`.

TEEC_Result TEECS_Boost | ( | TEEC_Session * | session | ) |

`#include <tees_client_api.h>`

The function enables performance boosting for current TA session.

Parameters

  [in] | session | the session of a TA.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS | invalid parameters.

Example of usage:

res = TEECS_Boost(&session);
if (res) {
// Error handling
}
// Invoking commands with boosted performance
res = TEECS_Unboost(&session);
if (res) {
// Error handling
}

TEEC_Result TEECS_GetSessionId | ( | const TEEC_Session * | session,
|  | TEEC_UUID * | session_id
| ) |  |

`#include <tees_client_api.h>`

Function gets session ID.

Parameters

  [in] | session | pointer to a Session structure to open.
  [in] | session_id | identificator of Session structure.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS |
  TEEC_ERROR_GENERIC |

Example of usage:

TODO: provide workable example

TEEC_Result TEECS_OpenSession | ( | TEEC_Context * | context,
|  | TEEC_Session * | session,
|  | const TEEC_UUID * | destination,
|  | const void * | ta_image,
|  | const size_t | ta_image_size,
|  | uint32_t | connectionMethod,
|  | const void * | connectionData,
|  | TEEC_Operation * | operation,
|  | uint32_t * | returnOrigin
| ) |  |

`#include <tees_client_api.h>`

The function opens TA which is located not exactly in /vendor/tee directory. Function behaves the same way as TEEC_OpenSession(), but provides two additional parameters. `ta_image` and `ta_image_size`.

Parameters

  [in] | context | pointer to a session context.
  [in] | session | pointer to a session structure to open.
  [in] | destination | pointer to a structure containing the TA uuid.
  [in] | ta_image | pointer to TA image.
  [in] | ta_image_size | size of TA image.
  [in] | connectionMethod | the method of connection to use.
  [in] | connectionData | any necessary data required to support the connection method chosen.
  [in] | operation | pointer to an operation containing parameters to exchange with the TA.
  [in] | returnOrigin | pointer to a variable which will contain the return origin.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS | wrong parameters were passed to the function.

Example of usage:

int fd = open(TA_NAME, O_RDONLY);
struct stat st;
fstat(fd, &st);
void *ta_image = malloc(st.st_size);
size_t ta_image_size = read(fd, (char *)ta_image, st.st_size);
close(fd);
res = TEECS_OpenSession(context,
&session,
&ta_uuid,
ta_image,
ta_image_size,
0,
NULL,
NULL,
&returnOrigin);

TEEC_Result TEECS_OpenSession1 | ( | TEEC_Context * | context,
|  | TEEC_Session * | session,
|  | const TEEC_UUID * | destination,
|  | const char * | destination_path,
|  | uint32_t | connectionMethod,
|  | const void * | connectionData,
|  | TEEC_Operation * | operation,
|  | uint32_t * | returnOrigin
| ) |  |

`#include <tees_client_api.h>`

The function opens TA which is located not exactly in /vendor/tee directory. Function behaves the same way as TEEC_OpenSession(), but provides one additional parameter. `destination_path` (e.g. /system/tee, /data/tee) wherever CA has appropriate permission.

Parameters

  [in] | context | pointer to a session context.
  [in] | session | pointer to a session structure to open.
  [in] | destination | pointer to a structure containing the TA uuid.
  [in] | destination_path | pointer to directory location
  [in] | connectionMethod | the method of connection to use.
  [in] | connectionData | any necessary data required to support the connection method chosen.
  [in] | operation | pointer to an operation containing parameters to exchange with the TA.
  [in] | returnOrigin | pointer to a variable which will contain the return origin.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS | wrong parameters were passed to the function.

Example of usage:

const char *path = "/system/tee/";
res = TEECS_OpenSession1(context,
&session,
&ta_uuid,
path,
0,
NULL,
NULL,
&returnOrigin);

TEEC_Result TEECS_SetCluster | ( | TEEC_Session * | session,
|  | Cluster | cluster
| ) |  |

`#include <tees_client_api.h>`

The function sets TA (main thread and its descendants, created after call) to desired cpu cluster.

Parameters

  [in] | session | the session of a TA.
  [in] | cluster | one of the value `CLUSTER_LITTLE`, `CLUSTER_BIG`, or `CLUSTER_DEFAULT`.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS | invalid parameters.

Example of usage: Use this function carefully. It will affect main thread (and its descendants) for any subsequent TEEC_* call till session termination. Use 'TEECS_SetCluster(session, CLUSTER_DEFAULT)' when you don't need any specific cluster anymore.

TODO: provide workable example

TEEC_Result TEECS_SetCryptoClk | ( | TEEC_Context * | context,
|  | uint32_t | state
| ) |  |

`#include <tees_client_api.h>`

The function switches crypto clocks ON/OFF Initially designed to reduce power consuption on Qualcomm chipsets A reference counter is maintained in TEEC_ContextImp.

Parameters

  [in] | context | session contex.
  [in] | state | one of the value `DISABLE_CRYPTO_CLK`, `ENABLE_CRYPTO_CLK`.

Return values

  TEEC_SUCCESS | in case of success.

Example of usage:

TODO: provide workable example

TEEC_Result TEECS_TADebugServiceCtl | ( | ta_debug_service_type_t | type,
|  | const TEEC_UUID * | monitoredTA,
|  | const TEEC_UUID * | monitoredSession
| ) |  |

`#include <tees_client_api.h>`

Create a request into underlying TEE implementation to provide TEE TA Debug functionality for current Client Application.

Parameters

  [in] | type | Specifies what kind of TEE TA Debug Service current Client Application wants to get. `type` is an enumeration of ta_debug_service_type_t.
  [in] | monitoredTA | Pointer to TEEC_UUID. It's a UUID of the Monitored TA. This value is optional and may be Nil UUID to indicate an empty value. If a Nil UUID is specified, then all debuggable sessions on the monitored TEE shall report DLM output to current Client Application and the `monitoredSession` value is ignored. Refer to TEE TA Debug Specification, 5.3.4 Client Side DLM_State Structure.
  [in] | monitoredSession | Pointer to TEEC_UUID. It's a session ID of connection established between Client Application and its Trusted Application being debugged (a.k.a Monitored TA). Client Application can obtain session ID by means of call to TEECS_GetSessionId(). Refer to TEE TA Debug Specification, 5.3.4 Client Side DLM_State Structure.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_NOT_IMPLEMENTED | when part of functionality is not implemented yet.
  TEEC_ERROR_BAD_PARAMETERS | wrong parameters were passed to the function.
  TEEC_ERROR_COMMUNICATION | can't establish communication with service daemon or communication error.
  TEEC_ERROR_BAD_STATE | DLM service can not perform operation, because client's stdout and stderr are closed.

Example of usage:

TODO: provide workable example

TEEC_Result TEECS_Unboost | ( | TEEC_Session * | session | ) |

`#include <tees_client_api.h>`

The function disables performance boosting for current TA session.

Parameters

  [in] | session | the session of a TA.

Return values

  TEEC_SUCCESS | in case of success.
  TEEC_ERROR_BAD_PARAMETERS | invalid parameters.

Example of usage:

res = TEECS_Boost(&session);
if (res) {
// Error handling
}
// Invoking commands with boosted performance
res = TEECS_Unboost(&session);
if (res) {
// Error handling
}

TEEC_Result TEECS_WaitTADeath | ( | TEEC_Session * | session | ) |

`#include <tees_client_api.h>`

Wait for unexpected death of TA.

Parameters

  [in] | session | Specifies successfully opened session with monitored TA.

Return values

  TEEC_ERROR_TARGET_DEAD | monitored TA unexpectedly died.
  TEEC_ERROR_BAD_PARAMETERS | wrong parameters were passed to the function.
  TEEC_ERROR_COMMUNICATION | communication with tzdaemon failed.
  TEEC_ERROR_ITEM_NOT_FOUND | client context haven't been found.