GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> FILE / dev > file_upl / sun-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » SVC » source » FILE » dev » FILE

FILE_upl.h File Reference

File Upload State Machine Library. More...


Classes

struct  _FILE_Upl_Info

Typedefs

typedef enum _FILE_Upl_State FILE_Upl_State
typedef struct _FILE_Upl FILE_Upl
typedef struct _FILE_Upl_Info FILE_Upl_Info

Enumerations

enum  _FILE_Upl_State {
  FILE_UPL_STATE_START = 0,
  FILE_UPL_STATE_LOAD = 1,
  FILE_UPL_STATE_COMMIT = 2,
  FILE_UPL_STATE_ERROR = 3
}

Functions

FILE_Upl * FILE_uplGet (void)
 Get a pointer to the file upload state machine descriptor.
unsigned int FILE_uplInit (FILE_Upl *upl, void *fileBuf, unsigned int bufSize)
 Initialize the file upload state machine.
unsigned int FILE_uplPkt (FILE_Upl *upl, const void *pkt, FILE_Upl_Info *info)
 Announce the arrival of a packet to the state machine.
unsigned int FILE_uplReset (FILE_Upl *upl)
 Reset the file upload state machine.
unsigned int FILE_uplInfo (FILE_Upl *upl, FILE_Upl_Info *info)
 Get information about the file upload current state.
unsigned int FILE_uplExit (FILE_Upl *upl)
 Shutdown the file upload state machine.
unsigned int FILE_uplCommit (FILE_Upl *upl, unsigned int id, int validateOnly)
 Announce a file upload commit operation to the state machine.
unsigned int FILE_uplStart (FILE_Upl *upl, unsigned int size)
 Announce a file upload start operation to the state machine.
unsigned int FILE_uplData (FILE_Upl *upl, unsigned int offset, unsigned int size, const void *data)
 Announce a file upload next data operation to the state machine.
unsigned int FILE_uplCancel (FILE_Upl *upl)
 Announce a file upload cancel operation to the state machine.
unsigned int FILE_uplSetError (FILE_Upl *upl, unsigned int errCode)
 Set the file upload state machine error information.

Detailed Description

File Upload State Machine Library.

Author:
D.L. Wood
This library implements a simple state machine to help manage GLAST LAT file object uploads. The uploads arrive as a series of CCSDS telecommand packets. After initialization, the upload state machine is ready to accept packets. The state machine uses the user supplied buffer to assemble the file completely in memory. This allows for validation of the complete file data before the file is committed to storage. A File Upload Start telecommand announces the beginning of a new file upload. It also provides a byte size for the upload. A series of File Upload Data telecommands follow.

It is assumed that when FILE_uplPkt() is called, basic validation of the telecommand packet has already occured. Also, the state machine must be presented only telecommands with Application ID 0x641. The function FILE_uplPkt() will query the CCSDS packet header to get the Function Code. Only function codes 0 (File Upload Start), 1 (File Upload Cancel), 2 (File Upload Commit), and 3 (File Upload Data) are recognized.

The file to be loaded should already contain a valid LAT file object header (see constituent file_hdr). The prefixed file header is used to validate the complete file data set before allowing the upload to move from FILE_UPL_STATE_LOAD to FILE_UPL_STATE_COMMIT.

This implementation assumes that each CPU only maintains one global file upload state machine. This is reflected in the interface function FILE_uplGet(), which returns a pointer to the static instance of the state machine descriptor. No thread safety is provided internally. The one exception to this is when the FILE_Upl_Info structure is filled in. This operation is protected by a lock to allow one task to process the file upload telecommands while annother checks up on the current status.

Typedef Documentation

FILE_Upl

Public descriptor for file upload state machine instance.

FILE_Upl_Info

The typedef for _FILE_Upl_Info.

FILE_Upl_State

The typedef for _FILE_Upl_State.

Enumeration Type Documentation

enum _FILE_Upl_State

Codes indicating current state of file upload.

Enumerator:
FILE_UPL_STATE_START  State machine is initialized and waiting for upload start telecommand.
FILE_UPL_STATE_LOAD  State machine is waiting for the file data telecommands.
FILE_UPL_STATE_COMMIT  State machine has received the file commit telecommand and is ready to write the data.
FILE_UPL_STATE_ERROR  State machine has encountered error and must be reset before attempting a new upload.

Function Documentation

unsigned int FILE_uplCancel ( FILE_Upl *  upl  ) 

Announce a file upload cancel operation to the state machine.

Announces the arrival of a new file upload File Upload Data telecommand to the file upload state machine.

Parameters:
upl The upload state machine descriptor.
Returns:
A FILE MSG code.

References _FILE_Upl::check, FILE_UPL_MSG, and FILE_uplReset().

Referenced by FILE_uplPktCancel().

unsigned int FILE_uplCommit ( FILE_Upl *  upl,
unsigned int  id,
int  validateOnly 
)

Announce a file upload commit operation to the state machine.

PS

Prepares the file data in the upload buffer for writing to storage. Because the actual commit operation is environment specific, this function simple verifies that the file header information and file checksum are valid. Success will set the state of the file upload state machine to FILE_UPL_STATE_COMMIT. This is really a null state, and simply means that the user may now write the data in the upload buffer to storage. Call FILE_uplReset() when done to prepare the state machine for a new upload. The id_commit, and size_commit members are updated in the info structure.

Parameters:
upl The upload state machine descriptor.
id The file ID storage value.
validateOnly 0 = set state to FILE_UPL_STATE_ERROR if validation fails 1 = only return error code if validation fails
Returns:
A FILE MSG code.

References _FILE_Upl::check, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_STATE_COMMIT, FILE_UPL_STATE_LOAD, FILE_UPL_UNLOCK, FILE_uplError(), FILE_uplVerify(), _FILE_Upl_Info::id_commit, _FILE_Upl::info, and _FILE_Upl_Info::state.

Referenced by FILE_uplPktCommit().

unsigned int FILE_uplData ( FILE_Upl *  upl,
unsigned int  offset,
unsigned int  size,
const void *  data 
)

Announce a file upload next data operation to the state machine.

Announces the arrival of a new file upload File Upload Data telecommand to the file upload state machine.

Parameters:
upl The upload state machine descriptor.
offset The offset in bytes of the data from the beginning of the file.
size The size in bytes of the upload data.
data A pointer to the upload data.
Returns:
A FILE MSG code.

References _FILE_Upl_Info::buf_addr, _FILE_Upl::check, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_STATE_LOAD, FILE_UPL_UNLOCK, FILE_uplError(), _FILE_Upl::info, _FILE_Upl_Info::offset_current, _FILE_Upl_Info::pkt_count, _FILE_Upl_Info::size_current, _FILE_Upl_Info::size_total, and _FILE_Upl_Info::state.

Referenced by FILE_uplPktData().

unsigned int FILE_uplExit ( FILE_Upl *  upl  ) 

Shutdown the file upload state machine.

Released resources allocated by the file upload state machine. Note that releasing the file upload assembly buffer passed in the call to FILE_uplInit() is the user's responsibility.

Parameters:
upl The upload state machine descriptor.
Returns:
A FILE MSG code.

References _FILE_Upl::check, FILE_UPL_MSG, and _FILE_Upl::info_lock.

FILE_Upl* FILE_uplGet ( void   ) 

Get a pointer to the file upload state machine descriptor.

Returns a pointer to the global file upload state machine descriptor.

Returns:
The upload state machine descriptor.

unsigned int FILE_uplInfo ( FILE_Upl *  upl,
FILE_Upl_Info *  info 
)

Get information about the file upload current state.

Returns information about the current file upload state.

Parameters:
upl The upload state machine descriptor.
info Filled in with current state info upon return.
Returns:
A FILE MSG code.

References _FILE_Upl::check, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_UNLOCK, and _FILE_Upl::info.

Referenced by FILE_uplPkt().

unsigned int FILE_uplInit ( FILE_Upl *  upl,
void *  fileBuf,
unsigned int  bufSize 
)

Initialize the file upload state machine.

Initializes the file upload state machine.

Parameters:
upl The upload state machine descriptor.
fileBuf A pointer to a buffer that the loader can use for assembly of complete files from packet data fragments.
bufSize The size in bytes of fileBuf. This is also the largest size for a file upload.
Returns:
A FILE MSG code.

References _FILE_Upl_Info::buf_addr, _FILE_Upl::buf_size, _FILE_Upl::check, _FILE_Upl::chksum_size, FILE_UPL_MSG, FILE_uplReset(), _FILE_Upl::hdr_size, _FILE_Upl::info, and _FILE_Upl::info_lock.

unsigned int FILE_uplPkt ( FILE_Upl *  upl,
const void *  pkt,
FILE_Upl_Info *  info 
)

Announce the arrival of a packet to the state machine.

Announces the arrival of a new file upload telecommand CCSDS packet to the file upload state machine. On return, the state of the file upload, after processing the current packet, is given in info. If an error is encoutered, the upload state is set to FILE_UPL_STATE_ERROR.

Parameters:
upl The upload state machine descriptor.
pkt A pointer to the CCSDS file upload telecommand packet.
info Filled in with current state info upon return.
Returns:
A FILE MSG code.

References _FILE_Upl::check, FILE_APID_LAT_FILE_LOAD, FILE_UPL_MSG, FILE_uplError(), FILE_uplInfo(), FILE_uplPktCancel(), FILE_uplPktCommit(), FILE_uplPktData(), and FILE_uplPktStart().

unsigned int FILE_uplReset ( FILE_Upl *  upl  ) 

Reset the file upload state machine.

Resets the file upload state machine. All error conditions and previous file load state are cleared. A File Upload Start telecommand must be issued to start a new upload.

Parameters:
upl The upload state machine descriptor.
Returns:
A FILE MSG code.

References _FILE_Upl_Info::buf_addr, _FILE_Upl::buf_size, _FILE_Upl::check, _FILE_Upl_Info::error_code, _FILE_Upl_Info::error_count, FILE_UPL_CLEAR, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_STATE_START, FILE_UPL_UNLOCK, _FILE_Upl_Info::id_commit, _FILE_Upl::info, _FILE_Upl_Info::offset_current, _FILE_Upl_Info::pkt_count, _FILE_Upl_Info::size_commit, _FILE_Upl_Info::size_current, _FILE_Upl_Info::size_total, and _FILE_Upl_Info::state.

Referenced by FILE_uplCancel(), and FILE_uplInit().

unsigned int FILE_uplSetError ( FILE_Upl *  upl,
unsigned int  errCode 
)

Set the file upload state machine error information.

Records error information about file uploads. This can be used to update the file upload error state.

Parameters:
upl The upload state machine descriptor.
errCode The FILE MSG code indicating the error.
Returns:
A FILE MSG code.

References _FILE_Upl::check, _FILE_Upl_Info::error_code, _FILE_Upl_Info::error_count, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_STATE_ERROR, FILE_UPL_UNLOCK, _FILE_Upl::info, and _FILE_Upl_Info::state.

Referenced by FILE_uplError().

unsigned int FILE_uplStart ( FILE_Upl *  upl,
unsigned int  size 
)

Announce a file upload start operation to the state machine.

Announces the arrival of a new file upload File Upload Start telecommand CCSDS packet to the file upload state machine.

Parameters:
upl The upload state machine descriptor.
size The maximum size in bytes of the upload data set.
Returns:
A FILE MSG code.

References _FILE_Upl::buf_size, _FILE_Upl::check, FILE_UPL_LOCK, FILE_UPL_MSG, FILE_UPL_STATE_LOAD, FILE_UPL_STATE_START, FILE_UPL_UNLOCK, FILE_uplError(), _FILE_Upl::info, _FILE_Upl_Info::size_total, and _FILE_Upl_Info::state.

Referenced by FILE_uplPktStart().

Generated on Mon Mar 28 18:26:07 2011 by  doxygen 1.5.8