SEElib functions

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 returns the recommended number of processing threads on this system.

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.

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().

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.

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.

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.

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.

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.

This function marshals a command, submits it, waits for the response, and unmarshals it into a reply structure.

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:

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.

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.

This function frees a command structure and is equivalent to the generic stub function NFastApp_FreeCommand (described in the nCore CodeSafe API Documentation).

This function frees a reply structure and is equivalent to the generic stub function NFastApp_FreeReply (described in the nCore CodeSafe API Documentation).

This function returns an SEEJob reply to the nShield core so that the core can pass it to the calling application.

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).

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).

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).

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.

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.

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.

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.

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.

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.