Trusty fornisce API per lo sviluppo di due classi di applicazioni/servizi:
- Applicazioni o servizi affidabili eseguiti sul processore TEE
- Applicazioni normali/non attendibili che vengono eseguite sul processore principale e utilizzano i servizi forniti da applicazioni attendibili
L'API Trusty descrive generalmente il sistema di comunicazione tra processi (IPC) Trusty, comprese le comunicazioni con il mondo non sicuro. Il software in esecuzione sul processore principale può utilizzare le API Trusty per connettersi ad applicazioni/servizi affidabili e scambiare messaggi arbitrari con loro proprio come un servizio di rete su IP. Spetta all'applicazione determinare il formato dei dati e la semantica di questi messaggi utilizzando un protocollo a livello di app. La consegna affidabile dei messaggi è garantita dall'infrastruttura Trusty sottostante (sotto forma di driver in esecuzione sul processore principale) e la comunicazione è completamente asincrona.
Porti e canali
Le porte vengono utilizzate dalle applicazioni Trusty per esporre gli endpoint del servizio sotto forma di un percorso denominato a cui si connettono i client. Ciò fornisce un semplice ID servizio basato su stringhe che i client possono utilizzare. La convenzione di denominazione è la denominazione in stile DNS inverso, ad esempio com.google.servicename .
Quando un client si connette a una porta, il client riceve un canale per interagire con un servizio. Il servizio deve accettare una connessione in entrata e, quando lo fa, riceve anch'esso un canale. In sostanza, le porte vengono utilizzate per cercare i servizi e quindi la comunicazione avviene su una coppia di canali collegati (ad esempio, istanze di connessione su una porta). Quando un client si connette a una porta, viene stabilita una connessione simmetrica e bidirezionale. Utilizzando questo percorso full-duplex, client e server possono scambiarsi messaggi arbitrari fino a quando una delle parti non decide di interrompere la connessione.
Solo le applicazioni sicure sul lato sicuro oi moduli del kernel Trusty possono creare porte. Le applicazioni in esecuzione sul lato non protetto (nel mondo normale) possono connettersi solo ai servizi pubblicati dal lato protetto.
A seconda dei requisiti, un'applicazione attendibile può essere contemporaneamente un client e un server. Un'applicazione attendibile che pubblica un servizio (come server) potrebbe dover connettersi ad altri servizi (come client).
Gestire l'API
Gli handle sono numeri interi senza segno che rappresentano risorse come porte e canali, simili ai descrittori di file in UNIX. Dopo che gli handle sono stati creati, vengono inseriti in una tabella di handle specifica dell'applicazione e possono essere referenziati in seguito.
Un chiamante può associare dati privati a un handle utilizzando il metodo set_cookie() .
Metodi nell'API Handle
Gli handle sono validi solo nel contesto di un'applicazione. Un'applicazione non deve passare il valore di un handle ad altre applicazioni a meno che non sia specificato in modo esplicito. Un solo valore di handle deve essere interpretato confrontandolo con INVALID_IPC_HANDLE #define, che un'applicazione può utilizzare come indicazione che un handle non è valido o non è impostato.
set_cookie()
Associa i dati privati forniti dal chiamante a un handle specificato.
long set_cookie(uint32_t handle, void *cookie)
[in] handle : qualsiasi handle restituito da una delle chiamate API
[in] cookie : puntatore a dati arbitrari dello spazio utente nell'applicazione Trusty
[retval]: NO_ERROR in caso di successo, < 0 codice di errore in caso contrario
Questa chiamata è utile per gestire gli eventi che si verificano in un secondo momento dopo la creazione dell'handle. Il meccanismo di gestione degli eventi fornisce l'handle e il relativo cookie al gestore dell'evento.
È possibile attendere gli handle per gli eventi utilizzando la chiamata wait() .
aspettare()
Attende che si verifichi un evento su un determinato handle per un periodo di tempo specificato.
long wait(uint32_t handle_id, uevent_t *event, unsigned long timeout_msecs)
[in] handle_id : qualsiasi handle restituito da una delle chiamate API
[out] event : un puntatore alla struttura che rappresenta un evento che si è verificato su questo handle
[in] timeout_msecs : un valore di timeout in millisecondi; un valore di -1 è un timeout infinito
[retval]: NO_ERROR se si è verificato un evento valido entro un intervallo di timeout specificato; ERR_TIMED_OUT se è trascorso un timeout specificato ma non si è verificato alcun evento; < 0 per altri errori
In caso di successo ( retval == NO_ERROR ), la chiamata wait() riempie una struttura uevent_t specificata con informazioni sull'evento che si è verificato.
typedef struct uevent {
uint32_t handle; /* handle this event is related to */
uint32_t event; /* combination of IPC_HANDLE_POLL_XXX flags */
void *cookie; /* cookie associated with this handle */
} uevent_t;
Il campo event contiene una combinazione dei seguenti valori:
enum {
IPC_HANDLE_POLL_NONE = 0x0,
IPC_HANDLE_POLL_READY = 0x1,
IPC_HANDLE_POLL_ERROR = 0x2,
IPC_HANDLE_POLL_HUP = 0x4,
IPC_HANDLE_POLL_MSG = 0x8,
IPC_HANDLE_POLL_SEND_UNBLOCKED = 0x10,
… more values[TBD]
};
IPC_HANDLE_POLL_NONE - nessun evento è effettivamente in sospeso, il chiamante dovrebbe riavviare l'attesa
IPC_HANDLE_POLL_ERROR - si è verificato un errore interno non specificato
IPC_HANDLE_POLL_READY - dipende dal tipo di handle, come segue:
- Per le porte, questo valore indica che è presente una connessione in sospeso
- Per i canali, questo valore indica che è stata stabilita una connessione asincrona (vedi
connect()).
I seguenti eventi sono rilevanti solo per i canali:
-
IPC_HANDLE_POLL_HUP- indica che un canale è stato chiuso da un peer -
IPC_HANDLE_POLL_MSG- indica che c'è un messaggio in sospeso per questo canale -
IPC_HANDLE_POLL_SEND_UNBLOCKED- indica che un chiamante precedentemente bloccato può tentare di inviare nuovamente un messaggio (consultare la descrizione disend_msg()per i dettagli)
Un gestore di eventi deve essere preparato per gestire una combinazione di eventi specificati, poiché è possibile che più bit vengano impostati contemporaneamente. Ad esempio, per un canale è possibile avere contemporaneamente messaggi in sospeso e una connessione chiusa da un peer.
La maggior parte degli eventi sono appiccicosi. Persistono finché persiste la condizione sottostante (ad esempio vengono ricevuti tutti i messaggi in sospeso e vengono gestite le richieste di connessione in sospeso). L'eccezione è il caso dell'evento IPC_HANDLE_POLL_SEND_UNBLOCKED , che viene cancellato dopo una lettura e l'applicazione ha una sola possibilità per gestirlo.
Gli handle possono essere distrutti chiamando il metodo close() .
chiudere()
Distrugge la risorsa associata all'handle specificato e la rimuove dalla tabella degli handle.
long close(uint32_t handle_id);
[in] handle_id : handle per distruggere
[retval]: 0 in caso di successo; un errore negativo altrimenti
API del server
Un server inizia creando una o più porte denominate che rappresentano i suoi endpoint di servizio. Ogni porta è rappresentata da una maniglia.
Metodi nell'API del server
port_create()
Crea una porta di servizio denominata.
long port_create (const char *path, uint num_recv_bufs, size_t recv_buf_size, uint32_t flags)
[in] path : il nome della stringa della porta (come descritto sopra). Questo nome dovrebbe essere univoco in tutto il sistema; i tentativi di creare un duplicato falliranno.
[in] num_recv_bufs : il numero massimo di buffer che un canale su questa porta può pre-allocare per facilitare lo scambio di dati con il client. I buffer vengono conteggiati separatamente per i dati che vanno in entrambe le direzioni, quindi specificare 1 qui significherebbe che 1 buffer di invio e 1 di ricezione sono preallocati. In generale, il numero di buffer richiesti dipende dall'accordo di protocollo di livello superiore tra client e server. Il numero può essere minimo 1 in caso di protocollo molto sincrono (invia messaggio, ricevi risposta prima di inviarne un altro). Ma il numero può essere maggiore se il client prevede di inviare più di un messaggio prima che possa apparire una risposta (ad esempio, un messaggio come prologo e un altro come comando vero e proprio). I set di buffer allocati sono per canale, quindi due connessioni separate (canali) avrebbero set di buffer separati.
[in] recv_buf_size : dimensione massima di ogni singolo buffer nel set di buffer sopra. Questo valore dipende dal protocollo e limita in modo efficace la dimensione massima del messaggio che è possibile scambiare con il peer
[in] flags : una combinazione di flag che specifica il comportamento aggiuntivo della porta
Questo valore dovrebbe essere una combinazione dei seguenti valori:
IPC_PORT_ALLOW_TA_CONNECT : consente una connessione da altre app sicure
IPC_PORT_ALLOW_NS_CONNECT - consente una connessione dal mondo non sicuro
[retval]: gestisce la porta creata se non negativa o un errore specifico se negativo
Il server quindi esegue il polling dell'elenco degli handle di porta per le connessioni in entrata utilizzando la chiamata wait() . Alla ricezione di una richiesta di connessione indicata dal bit IPC_HANDLE_POLL_READY impostato nel campo event della struttura uevent_t , il server deve chiamare accept() per terminare di stabilire una connessione e creare un canale (rappresentato da un altro handle) che può quindi essere interrogato per i messaggi in arrivo .
accettare()
Accetta una connessione in entrata e ottiene un handle a un canale.
long accept(uint32_t handle_id, uuid_t *peer_uuid);
[in] handle_id : handle che rappresenta la porta a cui si è connesso un client
[out] peer_uuid : puntatore a una struttura uuud_t da riempire con l'UUID dell'applicazione client di connessione. Verrà impostato su tutti zeri se la connessione ha avuto origine dal mondo non sicuro
[retval]: gestisce un canale (se non negativo) su cui il server può scambiare messaggi con il client (o un codice di errore in caso contrario)
API client
Questa sezione contiene i metodi nell'API client.
Metodi nell'API client
Collegare()
Avvia una connessione a una porta specificata dal nome.
long connect(const char *path, uint flags);
[in] path : nome di una porta pubblicata da un'applicazione Trusty
[in] flags : specifica un comportamento aggiuntivo e facoltativo
[retval]: gestisce un canale su cui i messaggi possono essere scambiati con il server; errore se negativo
Se non vengono specificati flags (il parametro flags è impostato su 0), la chiamata a connect() avvia una connessione sincrona a una porta specificata che restituisce immediatamente un errore se la porta non esiste e crea un blocco finché il server non accetta altrimenti una connessione .
Questo comportamento può essere modificato specificando una combinazione di due valori, descritti di seguito:
enum {
IPC_CONNECT_WAIT_FOR_PORT = 0x1,
IPC_CONNECT_ASYNC = 0x2,
};
IPC_CONNECT_WAIT_FOR_PORT - forza una chiamata connect() ad attendere se la porta specificata non esiste immediatamente al momento dell'esecuzione, invece di fallire immediatamente.
IPC_CONNECT_ASYNC - se impostato, avvia una connessione asincrona. Un'applicazione deve eseguire il polling dell'handle restituito (richiamando wait() per un evento di completamento della connessione indicato dal bit IPC_HANDLE_POLL_READY impostato nel campo dell'evento della struttura uevent_t prima di avviare il normale funzionamento.
API di messaggistica
Le chiamate API di messaggistica consentono l'invio e la lettura di messaggi su una connessione (canale) stabilita in precedenza. Le chiamate API di messaggistica sono le stesse per server e client.
Un client riceve un handle a un canale emettendo una chiamata connect() e un server riceve un handle del canale da una chiamata accept() , descritta sopra.
Struttura di un messaggio Trusty
Come mostrato di seguito, i messaggi scambiati dall'API Trusty hanno una struttura minima, lasciando al server e al client di concordare sulla semantica dei contenuti effettivi:
/*
* IPC message
*/
typedef struct iovec {
void *base;
size_t len;
} iovec_t;
typedef struct ipc_msg {
uint num_iov; /* number of iovs in this message */
iovec_t *iov; /* pointer to iov array */
uint num_handles; /* reserved, currently not supported */
handle_t *handles; /* reserved, currently not supported */
} ipc_msg_t;
Un messaggio può essere composto da uno o più buffer non contigui rappresentati da un array di strutture iovec_t . Trusty esegue letture e scritture a dispersione su questi blocchi utilizzando l'array iov . Il contenuto dei buffer che può essere descritto dall'array iov è completamente arbitrario.
Metodi nell'API di messaggistica
send_msg()
Invia un messaggio su un canale specificato.
long send_msg(uint32_t handle, ipc_msg_t *msg);
[in] handle : handle al canale su cui inviare il messaggio
[in] msg : puntatore alla ipc_msg_t structure descrive il messaggio
[retval]: numero totale di byte inviati in caso di successo; un errore negativo altrimenti
Se il client (o il server) sta tentando di inviare un messaggio sul canale e non c'è spazio nella coda dei messaggi peer di destinazione, il canale potrebbe entrare in uno stato di blocco dell'invio (questo non dovrebbe mai accadere per un semplice protocollo di richiesta/risposta sincrona ma potrebbe accadere in casi più complicati) che viene indicato restituendo un codice di errore ERR_NOT_ENOUGH_BUFFER . In tal caso il chiamante deve attendere che il peer liberi spazio nella sua coda di ricezione recuperando i messaggi di gestione e ritiro, indicati dal bit IPC_HANDLE_POLL_SEND_UNBLOCKED impostato nel campo event della struttura uevent_t restituito dalla chiamata wait() .
get_msg()
Ottiene meta-informazioni sul messaggio successivo in una coda di messaggi in arrivo
di un canale specificato.
long get_msg(uint32_t handle, ipc_msg_info_t *msg_info);
[in] handle : handle del canale su cui deve essere recuperato un nuovo messaggio
[out] msg_info : Struttura delle informazioni del messaggio descritta come segue:
typedef struct ipc_msg_info {
size_t len; /* total message length */
uint32_t id; /* message id */
} ipc_msg_info_t;
A ogni messaggio viene assegnato un ID univoco nell'insieme di messaggi in sospeso e viene compilata la lunghezza totale di ciascun messaggio. Se configurato e consentito dal protocollo, possono esserci più messaggi in sospeso (aperti) contemporaneamente per un particolare canale.
[retval]: NO_ERROR in caso di successo; un errore negativo altrimenti
read_msg()
Legge il contenuto del messaggio con l'ID specificato a partire dall'offset specificato.
long read_msg(uint32_t handle, uint32_t msg_id, uint32_t offset, ipc_msg_t *msg);
[in] handle : handle del canale da cui leggere il messaggio
[in] msg_id : ID del messaggio da leggere
[in] offset : offset nel messaggio da cui iniziare la lettura
[in] msg : puntatore alla struttura ipc_msg_t che descrive un insieme di buffer in cui memorizzare i dati dei messaggi in arrivo
[retval]: numero totale di byte archiviati nei buffer dst in caso di successo; un errore negativo altrimenti
Il metodo read_msg può essere chiamato più volte a partire da un offset diverso (non necessariamente sequenziale) secondo necessità.
put_msg()
Ritira un messaggio con un ID specificato.
long put_msg(uint32_t handle, uint32_t msg_id);
[in] handle : handle del canale su cui è arrivato il messaggio
[in] msg_id : ID del messaggio ritirato
[retval]: NO_ERROR in caso di successo; un errore negativo altrimenti
Non è possibile accedere al contenuto del messaggio dopo che un messaggio è stato ritirato e il buffer che occupava è stato liberato.
API del descrittore di file
L'API del descrittore di file include le chiamate read() , write() e ioctl() . Tutte queste chiamate possono operare su un insieme predefinito (statico) di descrittori di file tradizionalmente rappresentati da piccoli numeri. Nell'implementazione corrente, lo spazio del descrittore di file è separato dallo spazio dell'handle IPC. L'API del descrittore di file in Trusty è simile a un'API tradizionale basata su un descrittore di file.
Per impostazione predefinita, ci sono 3 descrittori di file predefiniti (standard e noti):
- 0 - ingresso standard. L'implementazione predefinita di standard input
fdè no-op (poiché non ci si aspetta che le applicazioni affidabili abbiano una console interattiva), quindi leggere, scrivere o invocareioctl()sufd0 dovrebbe restituire un erroreERR_NOT_SUPPORTED. - 1 - uscita standard. I dati scritti sull'output standard possono essere instradati (a seconda del livello di debug LK) a UART e/o a un registro di memoria disponibile sul lato non sicuro, a seconda della piattaforma e della configurazione. I log e i messaggi di debug non critici dovrebbero essere inseriti nell'output standard. I metodi
read()eioctl()non sono operativi e dovrebbero restituire un erroreERR_NOT_SUPPORTED. - 2 - errore standard. I dati scritti nell'errore standard devono essere instradati all'UART o al registro di memoria disponibile sul lato non protetto, a seconda della piattaforma e della configurazione. Si consiglia di scrivere solo messaggi critici per l'errore standard, poiché è molto probabile che questo flusso non sia limitato. I metodi
read()eioctl()non sono operativi e dovrebbero restituire un erroreERR_NOT_SUPPORTED.
Anche se questo insieme di descrittori di file può essere esteso per implementare più fds (per implementare estensioni specifiche della piattaforma), l'estensione dei descrittori di file deve essere esercitata con cautela. L'estensione dei descrittori di file è soggetta a creare conflitti e generalmente non è consigliata.
Metodi nell'API del descrittore di file
leggere()
Tenta di leggere fino a count i byte di dati da un descrittore di file specificato.
long read(uint32_t fd, void *buf, uint32_t count);
[in] fd : Descrittore di file da cui leggere
[out] buf : puntatore a un buffer in cui archiviare i dati
[in] count : numero massimo di byte da leggere
[retval]: numero restituito di byte letti; un errore negativo altrimenti
scrivere()
Scrive per count i byte di dati nel descrittore di file specificato.
long write(uint32_t fd, void *buf, uint32_t count);
[in] fd : Descrittore di file in cui scrivere
[out] buf : puntatore ai dati da scrivere
[in] count : numero massimo di byte da scrivere
[retval]: numero restituito di byte scritti; un errore negativo altrimenti
ioctl()
Richiama un comando ioctl specificato per un determinato descrittore di file.
long ioctl(uint32_t fd, uint32_t cmd, void *args);
[in] fd : Descrittore di file su cui invocare ioctl()
[in] cmd : il comando ioctl
[in/out] args : puntatore agli argomenti ioctl()
API varie
Metodi nell'API Varie
prendi tempo()
Restituisce l'ora di sistema corrente (in nanosecondi).
long gettime(uint32_t clock_id, uint32_t flags, uint64_t *time);
[in] clock_id : dipendente dalla piattaforma; passare zero per impostazione predefinita
[in] flags : riservato, dovrebbe essere zero
[in] time : puntatore a un valore int64_t in cui memorizzare l'ora corrente
[retval]: NO_ERROR in caso di successo; un errore negativo altrimenti
sonno nano()
Sospende l'esecuzione dell'applicazione chiamante per un periodo di tempo specificato e la riprende dopo tale periodo.
long nanosleep(uint32_t clock_id, uint32_t flags, uint64_t sleep_time)
[in] clock_id : riservato, dovrebbe essere zero
[in] flags : riservato, dovrebbe essere zero
[in] sleep_time : tempo di sospensione in nanosecondi
[retval]: NO_ERROR in caso di successo; un errore negativo altrimenti
Esempio di un server di applicazioni affidabile
L'applicazione di esempio seguente mostra l'utilizzo delle API precedenti. L'esempio crea un servizio "eco" che gestisce più connessioni in ingresso e riflette al chiamante tutti i messaggi ricevuti dai client originati dal lato protetto o non protetto.
#include <uapi/err.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <trusty_ipc.h>
#define LOG_TAG "echo_srv"
#define TLOGE(fmt, ...) \
fprintf(stderr, "%s: %d: " fmt, LOG_TAG, __LINE__, ##__VA_ARGS__)
# define MAX_ECHO_MSG_SIZE 64
static
const char * srv_name = "com.android.echo.srv.echo";
static uint8_t msg_buf[MAX_ECHO_MSG_SIZE];
/*
* Message handler
*/
static int handle_msg(handle_t chan) {
int rc;
struct iovec iov;
ipc_msg_t msg;
ipc_msg_info_t msg_inf;
iov.iov_base = msg_buf;
iov.iov_len = sizeof(msg_buf);
msg.num_iov = 1;
msg.iov = &iov;
msg.num_handles = 0;
msg.handles = NULL;
/* get message info */
rc = get_msg(chan, &msg_inf);
if (rc == ERR_NO_MSG)
return NO_ERROR; /* no new messages */
if (rc != NO_ERROR) {
TLOGE("failed (%d) to get_msg for chan (%d)\n",
rc, chan);
return rc;
}
/* read msg content */
rc = read_msg(chan, msg_inf.id, 0, &msg);
if (rc < 0) {
TLOGE("failed (%d) to read_msg for chan (%d)\n",
rc, chan);
return rc;
}
/* update number of bytes received */
iov.iov_len = (size_t) rc;
/* send message back to the caller */
rc = send_msg(chan, &msg);
if (rc < 0) {
TLOGE("failed (%d) to send_msg for chan (%d)\n",
rc, chan);
return rc;
}
/* retire message */
rc = put_msg(chan, msg_inf.id);
if (rc != NO_ERROR) {
TLOGE("failed (%d) to put_msg for chan (%d)\n",
rc, chan);
return rc;
}
return NO_ERROR;
}
/*
* Channel event handler
*/
static void handle_channel_event(const uevent_t * ev) {
int rc;
if (ev->event & IPC_HANDLE_POLL_MSG) {
rc = handle_msg(ev->handle);
if (rc != NO_ERROR) {
/* report an error and close channel */
TLOGE("failed (%d) to handle event on channel %d\n",
rc, ev->handle);
close(ev->handle);
}
return;
}
if (ev->event & IPC_HANDLE_POLL_HUP) {
/* closed by peer. */
close(ev->handle);
return;
}
}
/*
* Port event handler
*/
static void handle_port_event(const uevent_t * ev) {
uuid_t peer_uuid;
if ((ev->event & IPC_HANDLE_POLL_ERROR) ||
(ev->event & IPC_HANDLE_POLL_HUP) ||
(ev->event & IPC_HANDLE_POLL_MSG) ||
(ev->event & IPC_HANDLE_POLL_SEND_UNBLOCKED)) {
/* should never happen with port handles */
TLOGE("error event (0x%x) for port (%d)\n",
ev->event, ev->handle);
abort();
}
if (ev->event & IPC_HANDLE_POLL_READY) {
/* incoming connection: accept it */
int rc = accept(ev->handle, &peer_uuid);
if (rc < 0) {
TLOGE("failed (%d) to accept on port %d\n",
rc, ev->handle);
return;
}
handle_t chan = rc;
while (true){
struct uevent cev;
rc = wait(chan, &cev, INFINITE_TIME);
if (rc < 0) {
TLOGE("wait returned (%d)\n", rc);
abort();
}
handle_channel_event(&cev);
if (cev.event & IPC_HANDLE_POLL_HUP) {
return;
}
}
}
}
/*
* Main application entry point
*/
int main(void) {
int rc;
handle_t port;
/* Initialize service */
rc = port_create(srv_name, 1, MAX_ECHO_MSG_SIZE,
IPC_PORT_ALLOW_NS_CONNECT |
IPC_PORT_ALLOW_TA_CONNECT);
if (rc < 0) {
TLOGE("Failed (%d) to create port %s\n",
rc, srv_name);
abort();
}
port = (handle_t) rc;
/* enter main event loop */
while (true) {
uevent_t ev;
ev.handle = INVALID_IPC_HANDLE;
ev.event = 0;
ev.cookie = NULL;
/* wait forever */
rc = wait(port, &ev, INFINITE_TIME);
if (rc == NO_ERROR) {
/* got an event */
handle_port_event(&ev);
} else {
TLOGE("wait returned (%d)\n", rc);
abort();
}
}
return 0;
}
Il metodo run_end_to_end_msg_test() invia 10.000 messaggi in modo asincrono al servizio "echo" e gestisce le risposte.
static int run_echo_test(void)
{
int rc;
handle_t chan;
uevent_t uevt;
uint8_t tx_buf[64];
uint8_t rx_buf[64];
ipc_msg_info_t inf;
ipc_msg_t tx_msg;
iovec_t tx_iov;
ipc_msg_t rx_msg;
iovec_t rx_iov;
/* prepare tx message buffer */
tx_iov.base = tx_buf;
tx_iov.len = sizeof(tx_buf);
tx_msg.num_iov = 1;
tx_msg.iov = &tx_iov;
tx_msg.num_handles = 0;
tx_msg.handles = NULL;
memset (tx_buf, 0x55, sizeof(tx_buf));
/* prepare rx message buffer */
rx_iov.base = rx_buf;
rx_iov.len = sizeof(rx_buf);
rx_msg.num_iov = 1;
rx_msg.iov = &rx_iov;
rx_msg.num_handles = 0;
rx_msg.handles = NULL;
/* open connection to echo service */
rc = sync_connect(srv_name, 1000);
if(rc < 0)
return rc;
/* got channel */
chan = (handle_t)rc;
/* send/receive 10000 messages asynchronously. */
uint tx_cnt = 10000;
uint rx_cnt = 10000;
while (tx_cnt || rx_cnt) {
/* send messages until all buffers are full */
while (tx_cnt) {
rc = send_msg(chan, &tx_msg);
if (rc == ERR_NOT_ENOUGH_BUFFER)
break; /* no more space */
if (rc != 64) {
if (rc > 0) {
/* incomplete send */
rc = ERR_NOT_VALID;
}
goto abort_test;
}
tx_cnt--;
}
/* wait for reply msg or room */
rc = wait(chan, &uevt, 1000);
if (rc != NO_ERROR)
goto abort_test;
/* drain all messages */
while (rx_cnt) {
/* get a reply */
rc = get_msg(chan, &inf);
if (rc == ERR_NO_MSG)
break; /* no more messages */
if (rc != NO_ERROR)
goto abort_test;
/* read reply data */
rc = read_msg(chan, inf.id, 0, &rx_msg);
if (rc != 64) {
/* unexpected reply length */
rc = ERR_NOT_VALID;
goto abort_test;
}
/* discard reply */
rc = put_msg(chan, inf.id);
if (rc != NO_ERROR)
goto abort_test;
rx_cnt--;
}
}
abort_test:
close(chan);
return rc;
}
API e applicazioni mondiali non sicure
Una serie di servizi Trusty, pubblicati dal lato sicuro e contrassegnati con l'attributo IPC_PORT_ALLOW_NS_CONNECT , sono accessibili ai programmi del kernel e dello spazio utente in esecuzione sul lato non sicuro.
L'ambiente di esecuzione sul lato non protetto (kernel e spazio utente) è drasticamente diverso dall'ambiente di esecuzione sul lato protetto. Pertanto, anziché una singola libreria per entrambi gli ambienti, esistono due diversi set di API. Nel kernel, l'API client è fornita dal driver del kernel trusty-ipc e registra un nodo del dispositivo di caratteri che può essere utilizzato dai processi dello spazio utente per comunicare con i servizi in esecuzione sul lato sicuro.
Spazio utente Trusty IPC Client API
La libreria dell'API client Trusty IPC dello spazio utente è uno strato sottile sopra il nodo del dispositivo fd .
Un programma nello spazio utente avvia una sessione di comunicazione chiamando tipc_connect() , inizializzando una connessione a un servizio Trusty specificato. Internamente, la chiamata tipc_connect() apre un nodo dispositivo specificato per ottenere un descrittore di file e richiama una TIPC_IOC_CONNECT ioctl() con il parametro argp che punta a una stringa contenente un nome di servizio a cui connettersi.
#define TIPC_IOC_MAGIC 'r' #define TIPC_IOC_CONNECT _IOW(TIPC_IOC_MAGIC, 0x80, char *)
Il descrittore di file risultante può essere utilizzato solo per comunicare con il servizio per il quale è stato creato. Il descrittore di file dovrebbe essere chiuso chiamando tipc_close() quando la connessione non è più richiesta.
Il descrittore di file ottenuto dalla chiamata tipc_connect() si comporta come un tipico nodo del dispositivo di caratteri; il descrittore di file:
- Può essere commutato in modalità non bloccante, se necessario
- Può essere scritto utilizzando una chiamata standard
write()per inviare messaggi all'altro lato - Può essere sottoposto a polling (usando le chiamate
poll()oselect()) per la disponibilità dei messaggi in arrivo come normali descrittori di file - Può essere letto per recuperare i messaggi in arrivo
Un chiamante invia un messaggio al servizio Trusty eseguendo una chiamata di scrittura per l' fd specificato. Tutti i dati passati alla chiamata write() sopra vengono trasformati in un messaggio dal driver trusty-ipc. Il messaggio viene consegnato al lato sicuro dove i dati vengono gestiti dal sottosistema IPC nel kernel Trusty e instradati alla destinazione corretta e consegnati a un ciclo di eventi dell'app come evento IPC_HANDLE_POLL_MSG su un particolare handle di canale. A seconda del protocollo specifico del servizio, il servizio Trusty può inviare uno o più messaggi di risposta che vengono recapitati sul lato non protetto e inseriti nella coda di messaggi del descrittore del file di canale appropriato per essere recuperati dall'applicazione spazio utente read() chiamare.
tipc_connect()
Apre un nodo dispositivo tipc specificato e avvia una connessione a un servizio Trusty specificato.
int tipc_connect(const char *dev_name, const char *srv_name);
[in] dev_name : Percorso del nodo del dispositivo Trusty IPC da aprire
[in] srv_name : nome di un servizio Trusty pubblicato a cui connettersi
[retval]: descrittore di file valido in caso di esito positivo, -1 in caso contrario.
tipc_close()
Chiude la connessione al servizio Trusty specificato da un descrittore di file.
int tipc_close(int fd);
[in] fd : descrittore di file precedentemente aperto da una chiamata tipc_connect()
API client IPC affidabile del kernel
L'API client Trusty IPC del kernel è disponibile per i driver del kernel. L'API Trusty IPC dello spazio utente è implementata su questa API.
In generale, l'utilizzo tipico di questa API consiste in un chiamante che crea un oggetto struct tipc_chan utilizzando la funzione tipc_create_channel() e quindi utilizzando la chiamata tipc_chan_connect() per avviare una connessione al servizio Trusty IPC in esecuzione sul lato sicuro. La connessione al lato remoto può essere terminata chiamando tipc_chan_shutdown() seguito da tipc_chan_destroy() per ripulire le risorse.
Dopo aver ricevuto una notifica (tramite il callback handle_event() ) che una connessione è stata stabilita correttamente, un chiamante effettua le seguenti operazioni:
- Ottiene un buffer dei messaggi utilizzando la chiamata
tipc_chan_get_txbuf_timeout() - Compone un messaggio e
- Mette in coda il messaggio utilizzando il metodo
tipc_chan_queue_msg()per la consegna a un servizio Trusty (sul lato sicuro), a cui il canale è connesso
Dopo che l'accodamento è riuscito, il chiamante dovrebbe dimenticare il buffer dei messaggi perché il buffer dei messaggi alla fine ritorna al pool di buffer libero dopo l'elaborazione da parte del lato remoto (per il riutilizzo in seguito, per altri messaggi). L'utente deve chiamare tipc_chan_put_txbuf() solo se non riesce a mettere in coda tale buffer o se non è più richiesto.
Un utente API riceve messaggi dal lato remoto gestendo un callback di notifica handle_msg() (che viene chiamato nel contesto della coda di lavoro trusty-ipc rx ) che fornisce un puntatore a un buffer rx contenente un messaggio in arrivo da gestire.
Si prevede che l'implementazione del callback handle_msg() restituirà un puntatore a una struttura valida struct tipc_msg_buf . Può essere uguale al buffer dei messaggi in arrivo se viene gestito localmente e non è più necessario. In alternativa, può essere un nuovo buffer ottenuto da una chiamata tipc_chan_get_rxbuf() se il buffer in entrata è in coda per un'ulteriore elaborazione. Un buffer rx separato deve essere tracciato ed eventualmente rilasciato usando una chiamata tipc_chan_put_rxbuf() quando non è più necessario.
Metodi nell'API client IPC affidabile del kernel
tipc_create_channel()
Crea e configura un'istanza di un canale Trusty IPC per un particolare dispositivo trusty-ipc.
struct tipc_chan *tipc_create_channel(struct device *dev,
const struct tipc_chan_ops *ops,
void *cb_arg);
[in] dev : puntatore al trusty-ipc per il quale è stato creato il canale del dispositivo
[in] ops : puntatore a una struct tipc_chan_ops , con i callback specifici del chiamante compilati
[in] cb_arg : puntatore ai dati che verranno passati ai callback tipc_chan_ops
[retval]: puntatore a un'istanza appena creata di struct tipc_chan in caso di successo, ERR_PTR(err) altrimenti
In generale, un chiamante deve fornire due callback che vengono richiamati in modo asincrono quando si verifica l'attività corrispondente.
L' void (*handle_event)(void *cb_arg, int event) viene richiamato per notificare a un chiamante una modifica dello stato del canale.
[in] cb_arg : puntatore ai dati passati a una chiamata tipc_create_channel()
[in] event : un evento che può essere uno dei seguenti valori:
-
TIPC_CHANNEL_CONNECTED- indica una connessione riuscita al lato remoto -
TIPC_CHANNEL_DISCONNECTED- indica che il lato remoto ha negato la nuova richiesta di connessione o ha richiesto la disconnessione per il canale precedentemente connesso -
TIPC_CHANNEL_SHUTDOWN- indica che il lato remoto si sta spegnendo, terminando permanentemente tutte le connessioni
Il struct tipc_msg_buf *(*handle_msg)(void *cb_arg, struct tipc_msg_buf *mb) viene richiamato per fornire la notifica che un nuovo messaggio è stato ricevuto su un canale specificato:
- [in]
cb_arg: puntatore ai dati passati alla chiamatatipc_create_channel() - [in]
mb: puntatore a unastruct tipc_msg_bufche descrive un messaggio in arrivo - [retval]: l'implementazione del callback dovrebbe restituire un puntatore a una
struct tipc_msg_bufche può essere lo stesso puntatore ricevuto come parametrombse il messaggio è gestito localmente e non è più richiesto (oppure può essere un nuovo buffer ottenuto daltipc_chan_get_rxbuf()chiamata)
tipc_chan_connect()
Avvia una connessione al servizio Trusty IPC specificato.
int tipc_chan_connect(struct tipc_chan *chan, const char *port);
[in] chan : puntatore a un canale restituito dalla chiamata tipc_create_chan()
[in] port : puntatore a una stringa contenente il nome del servizio a cui connettersi
[retval]: 0 in caso di successo, un errore negativo in caso contrario
Il chiamante riceve una notifica quando viene stabilita una connessione ricevendo un callback handle_event .
tipc_chan_shutdown()
Termina una connessione al servizio Trusty IPC precedentemente avviata da una chiamata tipc_chan_connect() .
int tipc_chan_shutdown(struct tipc_chan *chan);
[in] chan : puntatore a un canale restituito da una chiamata tipc_create_chan()
tipc_chan_destroy()
Distrugge un canale IPC Trusty specificato.
void tipc_chan_destroy(struct tipc_chan *chan);
[in] chan : puntatore a un canale restituito dalla chiamata tipc_create_chan()
tipc_chan_get_txbuf_timeout()
Ottiene un buffer dei messaggi che può essere utilizzato per inviare dati su un canale specificato. Se il buffer non è immediatamente disponibile, il chiamante potrebbe essere bloccato per il timeout specificato (in millisecondi).
struct tipc_msg_buf * tipc_chan_get_txbuf_timeout(struct tipc_chan *chan, long timeout);
[in] chan : puntatore al canale a cui accodare un messaggio
[in] chan : Timeout massimo per attendere fino a quando il buffer tx diventa disponibile
[retval]: un buffer di messaggi valido in caso di successo, ERR_PTR(err) in caso di errore
tipc_chan_queue_msg()
Mette in coda un messaggio da inviare sui canali Trusty IPC specificati.
int tipc_chan_queue_msg(struct tipc_chan *chan, struct tipc_msg_buf *mb);
[in] chan : puntatore al canale a cui accodare il messaggio
[in] mb: puntatore al messaggio da mettere in coda (ottenuto da una chiamata tipc_chan_get_txbuf_timeout() )
[retval]: 0 in caso di successo, un errore negativo in caso contrario
tipc_chan_put_txbuf()
Rilascia il buffer dei messaggi Tx specificato precedentemente ottenuto da una chiamata tipc_chan_get_txbuf_timeout() .
void tipc_chan_put_txbuf(struct tipc_chan *chan,
struct tipc_msg_buf *mb);
[in] chan : puntatore al canale a cui appartiene questo buffer di messaggi
[in] mb : puntatore al buffer dei messaggi da rilasciare
[reval]: Nessuno
tipc_chan_get_rxbuf()
Ottiene un nuovo buffer dei messaggi che può essere utilizzato per ricevere messaggi sul canale specificato.
struct tipc_msg_buf *tipc_chan_get_rxbuf(struct tipc_chan *chan);
[in] chan : puntatore a un canale a cui appartiene questo buffer di messaggi
[retval]: un buffer di messaggi valido in caso di successo, ERR_PTR(err) in caso di errore
tipc_chan_put_rxbuf()
Rilascia un buffer di messaggi specificato precedentemente ottenuto da una chiamata tipc_chan_get_rxbuf() .
void tipc_chan_put_rxbuf(struct tipc_chan *chan,
struct tipc_msg_buf *mb);
[in] chan : puntatore a un canale a cui appartiene questo buffer di messaggi
[in] mb : puntatore a un buffer di messaggi da rilasciare
[reval]: Nessuno