SEElib functions
The file seelib.h
contains wrapper functions for the software interrupts.
SEElib_init
extern void SEElib_init(void);
This function initializes the SEElib
library.
It also checks that the SWI interface that was implemented by the nShield core matches the version that the SEE machine implements.
This function does not return on error. |
SEElib_RecProcessThreads
int
SEElib_RecProcessThreads(void);
This function returns the recommended number of processing threads on this system.
SEElib_StartProcessorThreads
struct ProcessThreadCtx; /* User-defined */
typedef struct SEElib_ProcessContext
{
struct ProcessThreadCtx *uc;
unsigned char *iobuf;
int iobuf_maxlen;
}
SEElib_ProcessContext;
typedef struct ProcessThreadCtx * (*SEEJobInitFn) (SEElib_ProcessContext *pC);
/* Function called during thread initialisation */
typedef int (*SEEJobFn) ( SEElib_ProcessContext *pC, M_Word tag, int in_len );
/* Function to process an SEEJob; data is sent in & out via pC->iobuf.
Returns length being returned.
*/
extern int SEElib_StartProcessorThreads(int nthreads, int stacksize, SEEJobInitFn
pfnInit, SEEJobFn pfnProcess);
This function causes the SEE library to start a number of processing threads.
Each thread has its own SEElib_ProcessContext
allocated, which remains constant throughout the life of the thread.
A working buffer for a given thread is allocated; the iobuf
member points to this buffer and iobuf_maxlen
is set to the size.
Data for the SEEJob
is passed in and out through this buffer.
For each thread, the supplied SEEJobInitFn
is called first, and the ProcessThreadCtx
pointer it returns is stored in the SEElib_ProcessContext
structure.
This structure is typically some convenient thread-local storage.
The pointer may be NULL if it is not required.
When a job arrives for the given thread, the supplied SEEJobFn
is called.
It is passed the SEElib_ProcessContext
pointer pC
, a tag, and a length (in_len
).
The SEEJob
data is at
pC→iobuf
, length in_len
. The tag is merely for information.
The function should process the data and leave a reply at pC→iobuf
. The return value from the function indicates the number of bytes to be returned from this buffer.
SEElib_GetUserDataLen
extern M_Word SEElib_GetUserDataLen (void);
This function gets the length in bytes of the UserData
block that was passed in to create this SEE World.
The function returns 0 if the UserData block has been freed with SEElib_ReleaseUserData()
.
SEElib_ReadUserData
extern int SEElib_ReadUserData ( M_Word offset, unsigned char *buf, M_Word len );
This function reads selected bytes from the UserData
block, starting at offset bytes in and continuing for len bytes.
It returns an M_Status
value.
SEElib_ReleaseUserData
extern void SEElib_ReleaseUserData(void);
This function frees the resources associated with the UserData
block.
Typically, if an SEE machine copies the UserData
block into some internal format on initialization, it should call this function on completion to avoid having two copies of the data in memory.
SEElib_InitComplete
extern void SEElib_InitComplete( M_Word status );
This function must be called as soon as the SEE World has been initialized. This call must be made as soon as the SEE World is ready to accept jobs or has decided that it cannot accept jobs.
The status
value forms the initstatus
value in the reply to the CreateSEEWorld
nCore API command.
SEElib_AwaitJob
extern int SEElib_AwaitJob( M_Word *tag_out, , unsigned char *buf, M_Word *len_io );
This function blocks and waits for the next SEEJob
in from the nShield core.
On entry, *buf
and *len_io
give the base and length of a buffer area to receive the job.
On return, *len_io
is set to the length delivered (if the job is received successfully). This buffer is a copy of the seeargs
field that was sent in to the SEEJob
command.
The *tag_out
value is the tag for this command.
It must be returned in the SEElib_ReturnJob
so that the nShield core associates the reply with this command.
The SEElib_AwaitJob
function returns an M_Status
, which is only likely to be OK
or BufferFull
.
If you use SEElib_StartProcessorThreads() , it calls this function automatically, and you should not call this function yourself.
|
SEElib_StartTransactListener
extern void SEElib_StartTransactListener(void);
This function starts the thread that listens for SEElib_Transact
calls and dispatches them.
This function must be called before any use is made of SEElib_Transact
.
SEElib_Transact
extern int SEElib_Transact(struct M_Command *cmd, struct M_Reply *buf);
This function marshals a command, submits it, waits for the response, and unmarshals it into a reply structure.
SEElib_MarshalSendCommand
extern int SEElib_MarshalSendCommand(M_Command *cmd);
This function marshals a command and places it on the input queue for processing by the nShield core.
The command takes a reference to an M_Command
structure, as described in the nCore CodeSafe API Documentation.
The SEE machine can submit any of the nCore API commands listed in the Basic commands and Key-Management commands sections of the nCore CodeSafe API Documentation except:
-
RetryFailedModule
-
GetWhichModule
-
MergeKeyIDs
.
If the SEE machine attempts to submit one of these commands, the nShield core returns a response with the status code NotAvailable
.
The SEElib_MarshalSendCommand
function returns an M_Status
value.
This value is OK
if the command was marshalled and transferred to the nShield core correctly.
Do not mix calls to SEE_Transact() and SEElib_MarshalSendCommand() and SEElib_GetUnmarshalResponse() , because the replies may be misdirected.
|
SEElib_GetUnmarshalResponse
extern int SEElib_GetUnmarshalResponse(M_Reply *buf);
If there is a reply in the input queue for this SEE World, this function returns the first job in the queue. Otherwise, it blocks and waits for the nShield core to return a job.
On return, M_Reply
contains the unmarshalled reply.
The SEElib_GetUnmarshalResponse
function returns an M_Status
value.
This value is OK
if the reply was unmarshalled successfully.
The return of this value does not necessarily mean that the command was completed successfully, only that the reply was unmarshalled.
You must also check the M_Status
within the reply.
SEElib_FreeCommand
extern int SEElib_FreeCommand(struct M_Command *cmd);
This function frees a command structure and is equivalent to the generic stub function NFastApp_FreeCommand
(described in the nCore CodeSafe API Documentation).
SEElib_FreeReply
extern int
SEElib_FreeReply(struct M_Reply *reply);
This function frees a reply structure and is equivalent to the generic stub function NFastApp_FreeReply
(described in the nCore CodeSafe API Documentation).
SEElib_ReturnJob
extern void SEElib_ReturnJob( M_Word tag, const unsigned char *data, unsigned int len );
This function returns an SEEJob
reply to the nShield core so that the core can pass it to the calling application.
If you use the SEElib_StartProcessorThreads() function, it calls SEElib_ReturnJob() for you.
|
The tag field must match the tag supplied in the SEElib_AwaitJob()
call that created the job.
The given data is copied away and forms the seereply
field of the SEEJob
reply (see the description of the SEEJob
command in the nCore CodeSafe API Documentation).
SEElib_SubmitCoreJob
extern int SEElib_SubmitCoreJob( const unsigned char *data, unsigned int len );
This function puts a job on the input queue for processing by the core.
The byte block is passed in data
and len
. It should be a full marshalled M_Command
with a valid tag at the start.
This function returns an M_Status
, which is typically OK
or BufferFull
(if len
is too big).
SEElib_GetCoreJob
extern int SEElib_GetCoreJob ( unsigned char *buf, M_Word *len_io );
This function blocks and waits for a job submitted to the core to be returned.
On entry, buf
points to a buffer of length (*len_io) max
. On exit, if successful, *len_io
is the length of bytes returned.
This function returns an M_Status
, which is typically OK
or BufferFull
(if len_io
is too big).
SEElib_GetUserDataLen
extern M_Word SEElib_GetUserDataLen ( void );
This function gets the length in bytes of the UserData block passed in to create this SEE World.
If this data has been discarded because SEElib_ReleaseUserData()
has been called, this function returns 0
.
SEElib_Submit
extern int SEElib_Submit(M_Command *cmd, M_Reply *reply, PEVENT ev, SEElib_ContextHandle tctx);
This function submits the command specified in cmd
. The transaction listener thread calls EventSet ev
, if ev
is non-NULL, when the reply returns for this command.
The reply is unmarshalled into reply
and tctx
is returned to the caller in SEElib_Query
.
Unlike SEElib_SubmitCoreJob
this function can be called at the same time as another thread is blocking in SEElib_Transact
.
SEElib_StartTransactListener
must have been called before this function is called.
SEElib_Query
extern int SEElib_Query(M_Reply **replyp, SEElib_ContextHandle *tctx_r);
This function is called to receive a reply that is being held by the transaction listener thread.
It is typically called after having been woken from EventWait
as a result of the transaction listener thread posting to the event passed in to SEElib_Submit
.
If *replyp
is NULL, SEElib_Query
accepts any returned reply, and *replyp
is changed to point to that reply.
If *replyp
is not NULL, the function accepts the reply specified; other replies are queued internally.
tctx_r
may be NULL.
If it is not, the tctx
used when submitting the reply is stored in *tctx_r
. SEElib_Query
can return, in addition to the usual return values, TransactionNotYetComplete
if the reply (or any reply if *replyp
was NULL) has not come back from the core yet.
SEElib_StartTransactListener
must have been called before this function is called.
SEElib_StartSEEJobListener
extern int SEElib_StartSEEJobListener(PEVENT ev);
This function starts the SEEJob
listener thread which blocks calling SEElib_AwaitJob
, caches the new job and then sets the event ev
if ev
is non-NULL.
Use SEElib_QuerySEEJob
to receive any SEEJobs
that have been cached by this listener thread, followed by SEElib_ReturnJob
to reply to the SEEJob
, then followed by SEElib_ReleaseSEEJob
to free the buffer.
It is safe to call this function multiple times. Calls after the first call will have no effect.
SEElib_QuerySEEJob
extern M_Status SEElib_QuerySEEJob( M_Word *tag_out, unsigned char **buf, M_Word *len );
This function is called to receive a SEEJob
that is being held by the SEEJob
listener thread.
It is typically called after having been woken from EventWait
as a result of the SEEJob
listener thread setting the event passed in to SEElib_StartSEEJobListener
.
buf
is set to the buffer containing the SEEJob, len
is set to the length of the data contained in buf
.
This function returns TransactionNotYetComplete
if there were no outstanding SEEJobs
.
SEElib_ReleaseSEEJob
extern void SEElib_ReleaseSEEJob( unsigned char **buf );
This function is called to release a buffer which was returned from SEElib_QuerySEEJob
. This function must be called after the buffer specified by buf
in a call to SEElib_QuerySEEJob
has been finished with.
This function is safe to call even if *buf
is NULL.
In addition, this function sets *buf
to NULL on completion.