GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> FBS / V0-3-1 > fbs_rtos / linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » OS » source » FBS » V0-3-1 » FBS

FBS_pubrtos.h File Reference

Public definitions for FBS facilities built into the RTOS. More...

#include <stdio.h>
#include <sys/types.h>

Classes

struct  _SIB_Info
 Contains address and size information about the various SIB board memory and register regions. More...

Defines

#define FILE_HDR_NAME_SIZE   (8)
 The size in bytes of the file name contained in a file header.
#define FILE_M_MODULE   ( 0x02000000 )
 Module number in the errno sense.
#define FILE_S_SUCCESS   ( FILE_M_MODULE | 0x0000 )
 File opened successfully (not a read-only request).
#define FILE_S_NOHED   ( FILE_M_MODULE | 0x0004 )
 File opened successfully (no FSW header found).
#define FILE_S_HEDNOCMP   ( FILE_M_MODULE | 0x0008 )
 File opened successfully (FSW header found, file not compressed).
#define FILE_S_HEDCMP   ( FILE_M_MODULE | 0x000c )
 File opened successfully (FSW header found, file compressed).
#define FILE_E_CORRUPT   ( FILE_M_MODULE | 0x0003 )
 File open failed (the adler32 checksum of the body failed).
#define FILE_E_NOMKDIR   ( FILE_M_MODULE | 0x0007 )
 File open failed (could not create directory for temporary file).
#define FILE_E_NOSLOT   ( FILE_M_MODULE | 0x000b )
 File open failed (no more slots to store temporary file info).
#define FILE_E_NOTMPOPN   ( FILE_M_MODULE | 0x000f )
 File open failed (could not open temporary file).
#define FILE_E_NOINFLAT   ( FILE_M_MODULE | 0x0013 )
 File open failed (inflation step failed).
#define FILE_E_NOREOPEN   ( FILE_M_MODULE | 0x0017 )
 File open failed (could not reopen temporary file read-only).
#define FILE_E_MMAPMODE   ( FILE_M_MODULE | 0x001b )
 Open mode read/write not supported for memory mapped files.
#define FILE_E_MMAPNAME   ( FILE_M_MODULE | 0x001f )
 Not a recognized memory mapped file name.
#define FILE_E_MMAPNOT   ( FILE_M_MODULE | 0x0023 )
 Requested memory mapped file not available on this system.
#define FILE_E_MMAPOPEN   ( FILE_M_MODULE | 0x0027 )
 Requested memory mapped file already open.
#define FILE_E_MMAPLOST   ( FILE_M_MODULE | 0x002b )
 Cannot locate memory mapped file through SIB directory.
#define FILE_E_MMAPHEAD   ( FILE_M_MODULE | 0x002f )
 Memory mapped file does not start with a valid header.
#define FILE_E_MMAPNOOP   ( FILE_M_MODULE | 0x0033 )
 Create and delete operations not supported.
File Device Definitions


#define FILE_L_MEM_DEVICES   (3)
#define FILE_L_MEM_FILES   (3)
#define FILE_DEV_NAME_BOOT   "/boot"
#define FILE_DEV_NAME_RAM   "/ram"
#define FILE_DEV_NAME_EE0   "/ee0"
#define FILE_DEV_NAME_EE1   "/ee1"
#define FILE_DEV_NAME_MEM   "/mem"
#define FILE_DEV_NAME_MM0   "/mm0"
#define FILE_DEV_NAME_MM1   "/mm1"
#define FILE_DEV_NUM_BOOT   (0)
#define FILE_DEV_NUM_RAM   (1)
#define FILE_DEV_NUM_EE0   (2)
#define FILE_DEV_NUM_EE1   (3)
#define FILE_DEV_NUM_MEM   (4)
#define FILE_DEV_NUM_MM0   (5)
#define FILE_DEV_NUM_MM1   (6)
#define FILE_DEV_NUM_USR   (7)
File Device Definitions (deprecated)


#define FILE_DEV_NAME_TMP   "/tmp"
#define FILE_DEV_NUM_TMP   (7)
File ID Utility Macros


#define FILE_ID_M_DEV   (0xe0000000)
#define FILE_ID_M_DIR   (0x1fc00000)
#define FILE_ID_M_FILE   (0x003fffff)
#define FILE_ID_S_DEV   (29)
#define FILE_ID_S_DIR   (22)
#define FILE_ID_S_FILE   (0)
#define FILE_ID_TO_NUM(_id, _dev, _dir, _file)
 Translates a file ID word into component numbers.
#define FILE_NUM_TO_ID(_id, _dev, _dir, _file)
 Translates file component numbers to an ID word.
File Path Utility Macros


#define FILE_PATH_STR_SIZE   (24)
 The number of bytes needed to hold a system file path string.
#define FILE_PATH_STR_SIZE_USR   (256)
 The number of bytes needed to hold a user-defined file path string.
#define FILE_ID_TO_PATH(_str, _dev, _dir, _file)
 Translates file component numbers to an ASCII path name.

Typedefs

typedef enum _FILE_Hdr_Version FILE_Hdr_Version
 Typedef for enum _FILE_Hdr_Version.
typedef enum
_FILE_Hdr_Compression_Flag 		FILE_Hdr_Compression_Flag
 Typedef for enum _FILE_Hdr_Compression_Flag.
typedef struct _SIB_Info SIB_Info
 Typedef for struct _SIB_Info.

Enumerations

enum  _FILE_Hdr_Version {
  FILE_HDR_VERSION_1 = 0x2000,
  FILE_HDR_VERSION_2 = 0x4000
}
 The file header version enumeration. Tracks format changes. More...
enum  _FILE_Hdr_Compression_Flag {
  FILE_HDR_UNCOMPRESSED = 0x0000,
  FILE_HDR_COMPRESSED = 0x1000
}
 The file header compression flag values. More...

Functions

File Manipulation Functions


unsigned int FILE_check (const char *fil, unsigned int *key, unsigned short *typ)
 Check the integrity of a file.
int FILE_close (int fd)
 Close a FSW file (regular, headed/not-headed, compressed/not-compressed).
unsigned int FILE_decodePrimary (unsigned char *buf, unsigned int cnt, unsigned int *ver, unsigned int *cmp, unsigned short *typ, unsigned int *key, unsigned int *fcs, unsigned int *len)
 Assuming buf points to a file header, decode it.
unsigned int FILE_getCompression (int fd)
 Get the compression flag associated with the file descriptor.
unsigned int FILE_getKey (int fd)
 Get the value of the key associated with the file descriptor.
const char * FILE_getMemDeviceName (unsigned int ddx)
const char * FILE_getMemFileName (unsigned int fdx)
int FILE_getName (int fd, char *nam, unsigned int len)
 Get the original file name associated with the file descriptor.
unsigned int FILE_getSize (int fd)
 Get the file header size associated with the file descriptor.
unsigned short FILE_getType (int fd)
 Get the value of the type associated with the file descriptor.
unsigned int FILE_getVersion (int fd)
 Get the file header version associated with the file descriptor.
unsigned int FILE_hdrCreate (void *buf, unsigned int length, unsigned int time, unsigned int chksum, unsigned short type, unsigned int key, FILE_Hdr_Compression_Flag compress, const char *name)
 Create a new file header.
unsigned int FILE_hdrGetChksum (const void *buf, unsigned int *chksum)
 Get the file checksum.
unsigned int FILE_hdrGetCompression (const void *buf, unsigned short *compress)
 Get the file compression flag.
unsigned int FILE_hdrGetKey (const void *buf, unsigned int *key)
 Get the file key.
unsigned int FILE_hdrGetLength (const void *buf, unsigned int *length)
 Get the file data size.
unsigned int FILE_hdrGetName (const void *buf, char *name)
 Get the file name string.
unsigned int FILE_hdrGetTime (const void *buf, unsigned int *time)
 Get the file timestamp.
unsigned int FILE_hdrGetType (const void *buf, unsigned short *type)
 Get the file type.
unsigned int FILE_hdrSizeof (void)
 Get the size of a file header.
unsigned int FILE_hdrVerify (const void *buf)
 Verify the integrety of a file header.
int FILE_open (const char *fil, int flg, mode_t mod)
 Open a FSW file (regular, headed/not-headed, compressed/not-compressed).
Module Loading Functions


unsigned int FILE_loadModuleByID (unsigned int id, int sym, void **mod)
 Load a FSW code module by file ID.
unsigned int FILE_loadModuleByName (const char *nam, int sym, void **mod)
 Load a FSW code module by file name.
unsigned int FILE_loadModuleSecondary (unsigned int id, int sym, void **mod, unsigned int *dat)
 Load a FSW code module by file ID (special for secondary boot).
File ID, Name and Path Manipulation Functions


unsigned int FILE_pathInit (const char *usrName5, const char *usrName6)
unsigned int FILE_pathSizeof (void)
 Get the size of a file path string.
unsigned int FILE_pathIdToNum (unsigned int id, unsigned int *dev, unsigned int *dir, unsigned int *file)
 Translates a file ID word into component numbers.
unsigned int FILE_pathNumToId (unsigned int *id, unsigned int dev, unsigned int dir, unsigned int file)
 Translates file component numbers to an ID word.
unsigned int FILE_pathIdToPath (unsigned int id, char *str)
 Translates file ID word to an ASCII path name.
unsigned int FILE_pathPathToId (const char *nam)
 Convert a file name to a file ID (if possible).
TFFS and RAM Disk Functions


unsigned int FILE_sysMemMount (void)
unsigned int FILE_sysRamCreate (void *addr, int size)
unsigned int FILE_sysTffsMount (int drv)
unsigned int FILE_sysTffsFormat (int drv, unsigned int offset)
unsigned int FILE_sysTffsCheck (int drv)
unsigned int FILE_sysTffsRepair (int drv)

Detailed Description

Public definitions for FBS facilities built into the RTOS. 

CVS $Id: FBS_pubrtos.h,v 1.5 2011/03/24 21:24:42 apw Exp $
Author:
A.P.Waite

Define Documentation

#define FILE_ID_TO_NUM ( _id,
_dev,
_dir,
_file   ) 

Value:

{                                                               \
    *(_dev)  = (((_id) & FILE_ID_M_DEV ) >> FILE_ID_S_DEV );    \
    *(_dir)  = (((_id) & FILE_ID_M_DIR ) >> FILE_ID_S_DIR );    \
    *(_file) = (((_id) & FILE_ID_M_FILE) >> FILE_ID_S_FILE);    \
}
Translates a file ID word into component numbers.

Parameters:
_id The file ID word
_dev Storage for the device number
_dir Storage for the directory number
_file Storage for the file number

Referenced by FILE_pathIdToNum(), and FILE_pathIdToPath().

#define FILE_ID_TO_PATH ( _str,
_dev,
_dir,
_file   ) 

Value:

snprintf((_str), FILE_PATH_STR_SIZE, "%s/d%03u/f%07u", \
                                 (_dev), (_dir), (_file));
Translates file component numbers to an ASCII path name.

Parameters:
_str Storage for the path string
_dev The device name
_dir The directory number
_file The file number

Referenced by FILE_pathIdToPath().

#define FILE_NUM_TO_ID ( _id,
_dev,
_dir,
_file   ) 

Value:

{                                                               \
    *(_id)  = (((_dev)  << FILE_ID_S_DEV ) & FILE_ID_M_DEV );   \
    *(_id) |= (((_dir)  << FILE_ID_S_DIR ) & FILE_ID_M_DIR );   \
    *(_id) |= (((_file) << FILE_ID_S_FILE) & FILE_ID_M_FILE);   \
}
Translates file component numbers to an ID word.

Parameters:
_id Storage for the file ID word
_dev The device number
_dir The directory number
_file The file number

Referenced by FILE_pathNumToId().

Enumeration Type Documentation

enum _FILE_Hdr_Compression_Flag

The file header compression flag values.

Enumerator:
FILE_HDR_UNCOMPRESSED  File data is not ZLIB compressed.
FILE_HDR_COMPRESSED  File data is ZLIB compressed.

enum _FILE_Hdr_Version

The file header version enumeration. Tracks format changes.

Enumerator:
FILE_HDR_VERSION_1  Original format. Obsolete
FILE_HDR_VERSION_2  Current format.

Function Documentation

unsigned int FILE_check ( const char *  fil,
unsigned int *  key,
unsigned short *  typ 
)

Check the integrity of a file.

Parameters:
fil (in) File name
key (out) File key (from header) (can be NULL)
typ (out) File type (from header) (can be NULL)
Return values:
FBS_SUCCESS File integrity check passed
FBS_CHKFAIL File interrity check failed
FILE_check() checks the integrity of a file. It treats the file assuming that it carries a regular FSW header. Anything other than a full flight software headed file with good integrity will return FBS_CHKFAIL (which is not reported internal to this routine). For further information about why an integrity check failed, the errno mechanism can be used.

References FILE_ACS_SIZE, FILE_decodePrimary(), FILE_E_CORRUPT, FILE_E_MMAPHEAD, and FILE_K_HDR_SIZ.

int FILE_close ( int  fd  ) 

Close a FSW file (regular, headed/not-headed, compressed/not-compressed).

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
0 Success
-1 Failure (use errno to retrieve further details)
FILE_close() is the complement to FILE_open(). The only value added of FILE_close() over close() is that FILE_close() will check the file descriptor of the file being closed, and if it corresponds to a temporary inflation file, it will delete the file.

References FBS_mtx__unlock(), _FILE_Stat::fd, FILE_findSlot(), FILE_L_TEMPNAME, and FILE_tempname().

Referenced by FILE_loadModule().

unsigned int FILE_decodePrimary ( unsigned char *  buf,
unsigned int  cnt,
unsigned int *  ver,
unsigned int *  cmp,
unsigned short *  typ,
unsigned int *  key,
unsigned int *  fcs,
unsigned int *  len 
)

Assuming buf points to a file header, decode it.

Parameters:
buf (in) Pointer to buffer containing supposed file header
cnt (in) Byte count in buffer pointed to by buf
ver (out) Header version number (0 if no file header)
cmp (out) Header compression flag (0 if no file header)
typ (out) File type (0xffff if no file header)
key (out) File key (0xffffffff if no file header)
fcs (out) File body checksum (0xffffffff if no file header)
len (out) File body length (0xffffffff if no file header)
Return values:
0 The buffer does not contain a file header
x Offset in buf to where the file body begins

References _FILE_PrimaryHeader::ctl, _FILE_PrimaryHeader::fcs, FILE_M_HDR_CMP, FILE_M_HDR_SIZ, FILE_M_HDR_VER, FILE_V_HDR_CMP, FILE_V_HDR_SIZ, FILE_V_HDR_VER, _FILE_PrimaryHeader::hcs, _FILE_PrimaryHeader::key, _FILE_PrimaryHeader::len, and _FILE_PrimaryHeader::typ.

Referenced by FILE_check(), and FILE_open().

unsigned int FILE_getCompression ( int  fd  ) 

Get the compression flag associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
1 File compressed
0 File not compressed
FILE_getCompression() returns the compression bit from the FSW header of a file if:

  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value 0 is returned. Note that this is the compression bit from the original file open. If the original file is compressed, FILE_open() automatically runs a decompression step and points the caller to a decompressed version of the file.

References _FILE_Stat::ctl, FBS_mtx__unlock(), FILE_findSlot(), FILE_K_HDR_CMP, and FILE_M_HDR_CMP.

unsigned int FILE_getKey ( int  fd  ) 

Get the value of the key associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
x Key value
-1 Failure (well OK, it's really 0xffffffff)
FILE_getKey() returns the key from the FSW header of a file if:

  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value 0xffffffff is returned.

References FBS_mtx__unlock(), FILE_findSlot(), and _FILE_Stat::key.

Referenced by FILE_loadModule().

int FILE_getName ( int  fd,
char *  nam,
unsigned int  len 
)

Get the original file name associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
nam (out) Buffer into which to place name
len (out) Maximum length of name buffer
Return values:
x True length of file name
-1 Failure (see below)
FILE_getName() returns the name of the file originally opened with FILE_open() if:

  • The nam pointer is not NULL
  • The len argument is greater than zero
  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value -1 is returned.

Assuming the above conditions are met, this routine will always return a zero terminated string in nam, even if nam is not sufficiently long to accomodate the full name. To check for this case, the caller should compare the string length of nam against the true name length, which is returned by this function.

References FBS_mtx__unlock(), FILE_findSlot(), and _FILE_Stat::nam.

unsigned int FILE_getSize ( int  fd  ) 

Get the file header size associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
x File header size
0 Guard value
FILE_getSize() returns the file header size from the FSW header of a file if:

  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value 0 is returned.

Note that the size returned is literally the number stored in the file header, and does not include the four bytes at the start of the header used to store the file header checksum.

References _FILE_Stat::ctl, FBS_mtx__unlock(), FILE_findSlot(), FILE_K_HDR_SIZ, and FILE_M_HDR_SIZ.

unsigned short FILE_getType ( int  fd  ) 

Get the value of the type associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
x Type value
-1 Failure (well OK, it's really 0xffff)
FILE_getType() returns the type from the FSW header of a file if:

  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value 0xffff is returned.

References FBS_mtx__unlock(), FILE_findSlot(), and _FILE_Stat::typ.

unsigned int FILE_getVersion ( int  fd  ) 

Get the file header version associated with the file descriptor.

Parameters:
fd (in) File descriptor (conventional meaning)
Return values:
x Type value
0 Failure
FILE_getVersion() returns the file header version from the FSW header of a file if:

  • The file was opened with FILE_open()
  • The file was opened read-only
  • The file has a header

If these conditions are not met, the guard value 0 is returned.

References _FILE_Stat::ctl, FBS_mtx__unlock(), FILE_findSlot(), FILE_K_HDR_VER, and FILE_M_HDR_VER.

unsigned int FILE_hdrCreate ( void *  buf,
unsigned int  length,
unsigned int  time,
unsigned int  chksum,
unsigned short  type,
unsigned int  key,
FILE_Hdr_Compression_Flag  compress,
const char *  name 
)

Create a new file header.

Parameters:
buf A pointer to the file header buffer.
length The size in bytes of file data to follow the file header.
time The file timestamp, in seconds.
chksum The checksum of the remainder of the file header and file data.
type The file type code.
key The file key value.
compress #FILE_HDR_UNCOMPRESSED - The file data following the header is uncompressed.
#FILE_HDR_COMPRESSED The file data following the header is compressed.
name The ASCII file name. This parameter should point to a buffer containing #FILE_HDR_NAME_SIZE characters.
Returns:
A FHDR MSG value.
Creates a file header in the buffer specified by buf. The user is resposible for actually writing the new header into file storage. This library only supports buffers whose total size is aligned on a 16-bit boundary. The function will fail with error #FILE_EHDRPARM if the length parameter is not correctly aligned.

References _FILE_Hdr::file_chksum_lsw, _FILE_Hdr::file_chksum_msw, FILE_HDR_M_COMPRESS, FILE_HDR_MSG, FILE_HDR_NAME_SIZE, FILE_HDR_SIZE, FILE_HDR_VERSION_2, _FILE_Hdr::file_info, _FILE_Hdr::file_key_lsw, _FILE_Hdr::file_key_msw, _FILE_Hdr::file_length_lsw, _FILE_Hdr::file_length_msw, _FILE_Hdr::file_name, FILE_swapHdr(), _FILE_Hdr::file_time_lsw, _FILE_Hdr::file_time_msw, _FILE_Hdr::file_type, _FILE_Hdr::hdr_chksum_lsw, and _FILE_Hdr::hdr_chksum_msw.

unsigned int FILE_hdrGetChksum ( const void *  buf,
unsigned int *  chksum 
)

Get the file checksum.

Parameters:
buf A pointer to the start of the file header buffer.
chksum Stores the checksum value.
Returns:
A FILE MSG value.
Returns the checksum of the remainder of the file header and file data.

References _FILE_Hdr::file_chksum_lsw, _FILE_Hdr::file_chksum_msw, and FILE_HDR_MSG.

unsigned int FILE_hdrGetCompression ( const void *  buf,
unsigned short *  compress 
)

Get the file compression flag.

Parameters:
buf A pointer to the start of the file header buffer.
compress Stores the compression flag value.
Returns:
A FILE MSG value.
Returns the file compression flag value.

References FILE_HDR_M_COMPRESS, FILE_HDR_MSG, and _FILE_Hdr::file_info.

unsigned int FILE_hdrGetKey ( const void *  buf,
unsigned int *  key 
)

Get the file key.

Parameters:
buf A pointer to the start of the file header buffer.
key Stores the key value.
Returns:
A FILE MSG value.
Returns the file key value.

References FILE_HDR_MSG, _FILE_Hdr::file_key_lsw, and _FILE_Hdr::file_key_msw.

unsigned int FILE_hdrGetLength ( const void *  buf,
unsigned int *  length 
)

Get the file data size.

Parameters:
buf A pointer to the start of the file header buffer.
length Stores the length value.
Returns:
A FILE MSG value.
Returns the size in bytes of file data following the file header.

References FILE_HDR_MSG, _FILE_Hdr::file_length_lsw, and _FILE_Hdr::file_length_msw.

unsigned int FILE_hdrGetName ( const void *  buf,
char *  name 
)

Get the file name string.

Parameters:
buf A pointer to the start of the file header buffer.
name Stores the name string. Should be at least FILE_HDR_NAME_SIZE bytes in size.
Returns:
A FILE MSG value.
Returns the file name string. The ASCII characters are copied to the user buffer indicated by name. The string is not NULL terminated after return.

References FILE_HDR_MSG, FILE_HDR_NAME_SIZE, and _FILE_Hdr::file_name.

unsigned int FILE_hdrGetTime ( const void *  buf,
unsigned int *  time 
)

Get the file timestamp.

Parameters:
buf A pointer to the start of the file header buffer.
time Stores the timestamp value.
Returns:
A FILE MSG value.
Returns the file timestamp.

References FILE_HDR_MSG, _FILE_Hdr::file_time_lsw, and _FILE_Hdr::file_time_msw.

unsigned int FILE_hdrGetType ( const void *  buf,
unsigned short *  type 
)

Get the file type.

Parameters:
buf A pointer to the start of the file header buffer.
type Stores the type value.
Returns:
A FILE MSG value.
Returns the file type code.

References FILE_HDR_MSG, and _FILE_Hdr::file_type.

unsigned int FILE_hdrSizeof ( void   ) 

Get the size of a file header.

Returns:
The header size.
Returns the size in bytes of a LAT file header.

References FILE_HDR_SIZE.

unsigned int FILE_hdrVerify ( const void *  buf  ) 

Verify the integrety of a file header.

Parameters:
buf A pointer to the start of the file header buffer.
Returns:
A FILE MSG value.
Verifies the format of a file header in buf. Calculates header checksum and compares it to value stored in header.

References FILE_HDR_M_LENGTH, FILE_HDR_M_VERSION, FILE_HDR_MSG, FILE_HDR_SIZE, FILE_HDR_VERSION_2, _FILE_Hdr::file_info, FILE_swapHdr(), _FILE_Hdr::hdr_chksum_lsw, and _FILE_Hdr::hdr_chksum_msw.

unsigned int FILE_loadModuleByID ( unsigned int  id,
int  sym,
void **  mod 
)

Load a FSW code module by file ID.

Parameters:
id (in) File ID
sym (in) Symbol loading flag (conventional VxWorks definition)
mod (out) Module handle (note 1)
Warning:
I can find no rationale for providing this functionality in the unix world, so the unix implementation simply (reports) and returns an error.
Note:
  1. Can be specified as a NULL pointer, in which case nothing is returned. If specified, it is set to the handle returned by VxWorks loadModule().
Return values:
FBS_CSBODY Body checksum mismatch
FBS_IMEMALOC Cannot allocate memory to read module
FBS_LOADFAIL Load module failed
FBS_MEMDVCRE Memory device create failed
FBS_MEMDVOPN Memory device open failed
FBS_NOOPEN Cannot open module
FBS_NOTIMPL Function not implemented (unix only)
FBS_OMEMALOC Cannot allocate memory to inflate module
FBS_SLURP File length mismatch
FBS_SUCCESS Success
FBS_ZLIBFAIL Inflation failed
FBS_ZLIBINIT Inflation initialization failed

unsigned int FILE_loadModuleByName ( const char *  nam,
int  sym,
void **  mod 
)

Load a FSW code module by file name.

Parameters:
nam (in) File name
sym (in) Symbol loading flag (note 1)
mod (out) Module handle (note 2)
Note:
  1. For VxWorks, this is the symbol loading control flag in the call to loadModule(). For unix, this is the mode flag to a dlopen() call.
  2. Can be specified as a NULL pointer, in which case nothing is returned. If specified, it is set to the handle returned by VxWorks loadModule().
Return values:
FBS_CSBODY Body checksum mismatch
FBS_IMEMALOC Cannot allocate memory to read module
FBS_LOADFAIL Load module failed
FBS_MEMDVCRE Memory device create failed
FBS_MEMDVOPN Memory device open failed
FBS_NAMENULL Module name is NULL
FBS_NOOPEN Cannot open module
FBS_NOTIMPL Function not implemented (unix only)
FBS_OMEMALOC Cannot allocate memory to inflate module
FBS_SLURP File length mismatch
FBS_SUCCESS Success
FBS_ZLIBFAIL Inflation failed
FBS_ZLIBINIT Inflation initialization failed

References FILE_loadModule(), and FILE_pathPathToId().

unsigned int FILE_loadModuleSecondary ( unsigned int  id,
int  sym,
void **  mod,
unsigned int *  dat 
)

Load a FSW code module by file ID (special for secondary boot).

Parameters:
id (in) File ID
sym (in) Symbol loading flag (conventional VxWorks definition)
mod (out) Module handle (note 1)
dat (out) Return extra information on error (note 2)
Warning:
I can find no rationale for providing this functionality in the unix world, so the unix implementation simply (reports) and returns an error.
Note:
  1. Can be specified as a NULL pointer, in which case nothing is returned. If specified, it is set to the handle returned by VxWorks loadModule().
  2. Can be specified as a NULL pointer, in which case nothing is returned. If specified, a more detailed error code is provided.
Return values:
FBS_CSBODY Body checksum mismatch
FBS_IMEMALOC Cannot allocate memory to read module
FBS_LOADFAIL Load module failed
FBS_MEMDVCRE Memory device create failed
FBS_MEMDVOPN Memory device open failed
FBS_NOOPEN Cannot open module
FBS_NOTIMPL Function not implemented (unix only)
FBS_OMEMALOC Cannot allocate memory to inflate module
FBS_SLURP File length mismatch
FBS_SUCCESS Success
FBS_ZLIBFAIL Inflation failed
FBS_ZLIBINIT Inflation initialization failed
FILE_loadModuleSecondary() is a courtesy entry point for use during a fully automated secondary boot. During this period, errors cannot be reported through standard communications channels (because they haven't been brought up yet), so errors are recorded in the boot diagnostics area for later retrieval by primary boot. To refine the error reporting the boot diagnostics allow an extra parameter to be saved. That is what is brought out through this interface.

int FILE_open ( const char *  fil,
int  flg,
mode_t  mod 
)

Open a FSW file (regular, headed/not-headed, compressed/not-compressed).

Parameters:
fil (in) File name
flg (in) Open flags (O_RDONLY, O_WRONLY, O_RDWR, O_CREAT)
mod (in) Access mode (only used for NFS file creation)
Return values:
x File descriptor
-1 Failure
Warning:
If you open a file with FILE_open(), you must close it with FILE_close().
FILE_open() is designed to overlay the classic open() routine, adding the ability to deal with special format files peculiar to flight software. The call structure is identical to open(). If the open mode is O_WRONLY or O_RDWR, FILE_open() and open() are indistinguishable. If the open mode is O_RDONLY, things start to get exciting.

Flight software files appear in three different formats:

  • Regular file
  • Prefixed by a header, uncompressed
  • Prefixed by a header, compressed

When FILE_open() is asked to open any of these formats, it will first inspect the file to classify it. The adler32 checksum in the header is very powerful here. Subsequent processing depends on the file format:

  • Regular file. Indistinguishable from open() on the same file.
  • Prefixed by a header, uncompressed. The body of the file is adler32 check-summed. If it passes, the caller is returned a regular file descriptor with the file pointer pointing to the first byte past the header.
  • Prefixed by a header, compressed. The body of the file is adler32 check-summed. If it passes, the file is inflated in a temporary file (in /tmp/d000 on unix, in /ram/d000 in VxWorks). The original file is closed, the inflated file is opened O_RDONLY, and a file descriptor for the inflated file is returned to the caller. The temporary file is deleted when the file is closed (though the caller must use FILE_close() to close the file, not a simple close() call).

In keeping with the idea that FILE_open() is modeled on open(), the errno method is used to return extra information. One unusual feature of this is that errno can contain helpful information, even when the file open is successful.

If the return value is not -1 (i.e. the open succeeded), errno can contain:

  • FILE_S_SUCCESS Successfully opened a regular file, not in O_RDONLY mode
  • FILE_S_NOHED Successfully opened a regular file, in O_RDONLY mode
  • FILE_S_HEDNOCMP Successfully opened an uncompressed file with FSW header
  • FILE_S_HEDCMP Successfully opened a compressed file with FSW header

If the return value is -1 (i.e. the open failed), errno, in addition to any of the regular values that open() can return, can contain:

  • FILE_E_CORRUPT Adler32 of file body failed
  • FILE_E_NOMKDIR Could not make a temporary directory for inflation
  • FILE_E_NOSLOT Could not allocate a temporary file slot
  • FILE_E_NOTMPOPN Could not open the temporary file
  • FILE_E_NOINFLAT File inflation failed
  • FILE_E_NOREPOEN Could not reopen the temporary file after inflation

If you wish to use these values for additional checking, note that errno is a four byte word encoded as two two-byte units. The most significant unit is a module number and the lower unit is the "error" number. The additional error codes defined by FILE_open() are module 0x200 (to avoid collisions with unix and VxWorks error codes), and the error numbers obey MSG conventions, i.e. if the least significant bit is clear, the operation was a success.

References _FILE_PrimaryHeader::ctl, _FILE_Stat::ctl, _FILE_Stat::fd, FILE_ACS_SIZE, FILE_decodePrimary(), FILE_E_CORRUPT, FILE_E_NOINFLAT, FILE_E_NOMKDIR, FILE_E_NOREOPEN, FILE_E_NOSLOT, FILE_E_NOTMPOPN, FILE_inflate(), FILE_K_BITALLOC, FILE_K_HDR_SIZ, FILE_L_NAME, FILE_L_TEMPNAME, FILE_M_HDR_CMP, FILE_S_HEDCMP, FILE_S_HEDNOCMP, FILE_S_NOHED, FILE_S_SUCCESS, FILE_tempname(), FILE_V_HDR_CMP, FILE_V_HDR_SIZ, FILE_V_HDR_VER, _FILE_Stat::key, MKDIR, _FILE_Stat::nam, and _FILE_Stat::typ.

Referenced by FILE_loadModule().

unsigned int FILE_pathIdToNum ( unsigned int  id,
unsigned int *  dev,
unsigned int *  dir,
unsigned int *  file 
)

Translates a file ID word into component numbers.

Parameters:
id The file ID word.
dev Storage for the device number.
dir Storage for the directory number.
file Storage for the file number.
Returns:
A FILE MSG value.
Breaks a file ID word into its numerical components, which are stored in the user supplied dev, dir, and file locations.

References FILE_DEV_NUM_MAX, and FILE_ID_TO_NUM.

unsigned int FILE_pathIdToPath ( unsigned int  id,
char *  str 
)

Translates file ID word to an ASCII path name.

Parameters:
id The file ID word.
str Storage for the file path string.
Returns:
A FILE MSG value.
Creates a file system path string from a set of file ID components. The result is stored in the user supplied str location. The resulting path string is appropriate for use with the file system API functions.

References dir, FILE_DEV_NUM_MAX, FILE_ID_TO_NUM, FILE_ID_TO_PATH, and FILE_ID_TO_PATH_USR.

unsigned int FILE_pathNumToId ( unsigned int *  id,
unsigned int  dev,
unsigned int  dir,
unsigned int  file 
)

Translates file component numbers to an ID word.

Parameters:
id Storage for the file ID word.
dev The device number.
dir The directory number.
file The file number.
Returns:
A FILE MSG value.
Composes a new file ID word from its numerical components. The result is stored in the user supplied id location.

References FILE_DEV_NUM_MAX, and FILE_NUM_TO_ID.

unsigned int FILE_pathPathToId ( const char *  nam  ) 

Convert a file name to a file ID (if possible).

Parameters:
nam (in) File name
Return values:
0xffffffff Could not translate file name
x File ID

References dir, and FILE_DEV_NUM_MAX.

Referenced by FILE_loadModuleByName().

unsigned int FILE_pathSizeof ( void   ) 

Get the size of a file path string.

Returns:
The path string size in bytes.
Returns the number of bytes needed to hold an on-board file path string.

References FILE_PATH_STR_SIZE_USR.

unsigned int FILE_sysRamCreate ( void *  addr,
int  size 
)

Creates, formats, and mounts a RAM disk partition.

Parameters:
addr The memory address of the RAM disk partition.
size The size in bytes of the RAM disk partition.

unsigned int FILE_sysTffsCheck ( int  drv  ) 

Runs the DOSFS chkdsk utility on the requested TFFS partition. Only the status is checked; no repairs to the partition file system are attempted.

Parameters:
drv The TFFS drive number for the bank to check.
Returns:
A FILE MSG code.

unsigned int FILE_sysTffsFormat ( int  drv,
unsigned int  offset 
)

Formats a TFFS file system for a raw TFFS non-volatile memory bank. Both the TFFS/FTL layer and the DOSFS layer are written to the media. The offset parameter allows a portion of a media memory bank to be used by boot software.

Parameters:
drv The TFFS drive number for the bank to format.
offset The offset in bytes from the bank base address at which the TFFS/FTL formatting should begin.

unsigned int FILE_sysTffsMount ( int  drv  ) 

Mounts a TFFS/DOSFS filesytem for use. The non-volatile memory bank must have previously been formatted with both the TFFS and DOSFS layers.

Parameters:
drv The TFFS drive number for the bank to format.

unsigned int FILE_sysTffsRepair ( int  drv  ) 

Runs the DOSFS chkdsk utility on the requested TFFS partition. If an error is found by the utility, repairs to the partition file system are attempted.

Parameters:
drv The TFFS drive number for the bank to repair.
Returns:
A FILE MSG code.

Generated on Fri Sep 30 17:58:31 2011 by  doxygen 1.5.8