www.beck-ipc.com

@CHIP-RTOS - Data Structures used in BIOS API


    IPC@CHIP® Documentation Index

Data Structures

Here are the data structures used by the @Chip-RTOS BIOS API.   All constants and data structures are defined in the header file BIOS_API.H

Notes:
  • Byte alignment is required for all data structures used within the API.

Content :

  • BiosDiskInfo
  • FILE_FIND
  • CmdFeedbackS
  • ProgFeedbackS
  • FS_FILETIME
  • LFN_FILE_FIND
  • ServerCredentials


  • BiosDiskInfo


                
    typedef struct
    {
        unsigned int  bytesPerSector;
        unsigned int  sectorsPerCluster;
        unsigned long freeClusters;
        unsigned long totalClusters;
    } BiosDiskInfo;

    Comments

    This structure is defined in the header file BIOS_API.H.   The BIOS SWI 0xA0 service 0x0A fills in this structure's data.

    The number of bytes disk free space can be calculated as

        FreeClusters * sectorsPerCluster * bytesPerSector

    and the drive's total number of bytes as

        TotalClusters * sectorsPerCluster * bytesPerSector

    Note that the sector size used by the file system is fixed at 512 bytes.

    Related Topics

    API function BIOS_DISK_INFO Get Disk Info

    Top of list
    Index page

    FILE_FIND


                
    typedef struct filefind {
    
        char           filename[12];   // Null terminated filename
        char           fileext[4];     // and extension
        unsigned short fileattr;       // MS-DOS file attributes
        short int      reserved;       // Reserved
    
        FS_FILETIME filetimestamp;     // Time & date last modified
    
        unsigned long   filesize ;     // File size
        char    szShort_Name[FS_SHORTBUF] ;
    
        // private_field[] area is used internally by the @Chip-RTOS.
        char            private_field[FFIND_PRIVATE_SIZE];
    
    } FILE_FIND ;

    Comments

    This structure is defined in the header file BIOS_API.H.   From the user's point of view this structure is read-only data.   No fields need to be initialized by the user prior to the BIOS_Fast_Findfirst call.   The @Chip-RTOS does the writing to this structure.

    filename
      A null terminated ASCII string containing the base portion of the file name prior to any extension part.   Note: This string length is at most 8 characters plus the null terminator in spite of the 12 byte declaration.

    fileext
      A null terminated ASCII string containing the extension portion of the file name.   This string may be empty if the file name has no extension.

    fileattr
      A bit field that specifies the file's attributes as defined by the following constants declared in BIOS_API.H:

        #define FJ_DA_NORMAL     0x00
        #define FJ_DA_RDONLY     0x01
        #define FJ_DA_HIDDEN     0x02
        #define FJ_DA_SYSTEM     0x04
        #define FJ_DA_VOLUME     0x08
        #define FJ_DA_DIRENT     0x10
        #define FJ_DA_ARCHIVE    0x20

      reserved
        This structure member is not used.

      filetimestamp
        The structure contains the time and date at which this file was last modified.

      filesize
        The total number of bytes in the file.

      szShort_Name
        This 14 byte buffer will hold a null terminated ASCII string containing the DOS file name.   This string can be up to 12 characters in length plus a terminating null character.   (Same information as in filename and fileext presented in a single string.)  

        Note:    This field is not present in SC1x @Chip-RTOS versions prior to SC1x version 1.20 @Chip-RTOS.

    private_field
      Internal state information needed by the @Chip-RTOS is held here.   The user must not change anything in this area between the BIOS_Fast_Findfirst call and the last BIOS_Fast_Findnext or BIOS_Fast_Finddone call.

      Note:    The size of this private field has been substantially reduced as of SC1x version 1.20 @Chip-RTOS.   When compatibility with older @Chip-RTOS versions is required by the user for some reason, then the FILEFIND_OLD_RTOS compilation constant must be defined prior to including the BIOS_API.H include file to restore this interface data structure back to its original size.   For example:

          #define FILEFIND_OLD_RTOS
          #include "clib.h"

    Related Topics

    API function BIOS_FAST_FINDFIRST Fast findfirst
    API function BIOS_FAST_FINDNEXT Fast findnext
    API function BIOS_FAST_FINDDONE Fast finddone
    LFN_FILE_FIND - Long File Name find structure

    Top of list
    Index page

    CmdFeedbackS


                
    typedef struct CmdFeedbackT
    {
        unsigned int    cfSize ;
        int             cfStatus ;
        unsigned long   cfProgress ;
        unsigned long   cfGoal ;
    
    }  CmdFeedbackS ;

    Comments

    This structure is defined in the header file BIOS_API.H.   A pointer to one of these structures in user memory is passed as the report argument to the BIOS_ExecuteExt() API to receive progress feedback during execution of either the COPY or FORMAT shell commands.

    cfSize
      This member is provisional. The API user should set this to sizeof(CmdFeedbackS) to assure compatibility with future @Chip-RTOS releases.

    cfStatus
      This is the result from the operation. Zero indicates success, +1 indicates operation is in progress and negative value indicates a failure. The user may want to preset this to some value like -99 in order for there to be a positive indication that the desired operation has been started.

      The FORMAT command has the single error value -1. The COPY command has the following set of error values to indicate why the operation failed:

        -1      Incorrect number of arguments found on command line
        -2      Buffer memory allocation failed
        -3      Unable to open the source file
        -4      Unable to create the destination file
        -5      Unable to create the destination file due to root directory being full.
        -6      Source file read failed
        -7      Destination file write failed

    cfProgress
      This up counter will be driven by the FORMAT or COPY command during execution. This value will first be reset to zero by the @Chip-RTOS and then will count up to the value set in cfGoal. The caller is welcome to zero this value before calling BIOS_ExecuteExt() if desired.

    cfGoal
      This value, set by the command, is the final count value that the cfProgress will reach when the operation has completed.


    Note that the percentage completion can be calculated as:

      percent = (100 * cfProgress) / cfGoal

    Note that prior to the cfStatus being set to +1 by the COPY or FORMAT command, the cfGoal member is not yet valid.


    Top of list
    Index page

    ProgFeedbackS


                
    typedef struct ProgFeedbackT
    {
        unsigned int    pfSize ;
        int             pfExitCode ;
    
    }  ProgFeedbackS ;

    Comments

    This structure is defined in the header file BIOS_API.H.   A pointer to one of these structures in user memory is passed as the report argument to the BIOS_ExecuteExt() API to receive a DOS program exit code.

    pfSize
      This member is provisional. To to assure compatibility with future @Chip-RTOS releases, the API user should set this to the size of the structure (which may be the size of a containing structure whose first two members are same as this ProgFeedbackS structure).

    pfExitCode
      This is the DOS exit code set by the system when the child program terminates.



    Top of list
    Index page

    FS_FILETIME


                
    typedef struct tag_filetimestamp
    {
        unsigned short int filedate;
        unsigned short int filetime;
    } FS_FILETIME ;

    Comments

    This structure is defined in the header file BIOS_API.H.

    filedate
      This is a bit field which encodes the files date as follows:

        B0-B4:     Day of month in range 1..31
        B5-B8:     Month of year in range 1..12
        B9-B15:    Year - 1980

      or in other words:

          filedate = ((year - 1980) shl 9) or (month shl 5) or day ;

    filetime
      This is a bit field which encodes the files date as follows:

        B0-B4:     Seconds/2 in range 0..29 (seconds scaled @B-1)
        B5-B10:    Minute in range 0..59
        B11-B15:   Hour in range 0..23

      or in other words:

          filetime = (hour shl 11) or (min shl 5) or (sec / 2);

    Related Topics

    API function BIOS_FAST_FINDFIRST Fast findfirst
    API function BIOS_LFN_FINDFIRST Long file name findfirst

    Top of list
    Index page

    LFN_FILE_FIND


                
    typedef struct LFN_filefind {
        char     far   *pszLong_Name ;          // FS_MAXLONGPATH size
    
        char            filename[12];           // Null terminated filename
        char            fileext[4];             // and extension
        unsigned short  fileattr;               // MS-DOS file attributes
        short int       reserved;               // Reserved
    
        FS_FILETIME filetimestamp;              // Time & date last modified
    
        unsigned long   filesize ;              // File size
        char            szShort_Name[FS_SHORTBUF] ; // DOS Alias
    
        // private_field[] area is used internally by the @Chip-RTOS.
        char            private_field[40];
    
    } LFN_FILE_FIND ;

    Comments

    This structure is defined in the header file BIOS_API.H.   From the user's point of view this structure is read-only data.   No fields need to be initialized by the user prior to the BIOS_LFN_Findfirst call.   The @Chip-RTOS does the writing to this structure.

    pszLong_Name
      The null terminated ASCII file name string of up to 260 characters is reported here by the long file name findfirst/findnext functions.   This memory is allocated by the @Chip-RTOS API and not by the caller.   Note that a final call to the BIOS_LFN_Find_Done function is required in order to release this memory unless either the BIOS_LFN_Findfirst or BIOS_LFN_Findnext had returned FALSE in which case the memory has already been released.

    filename
      A null terminated ASCII string containing the base portion of the short DOS 8.3 alias file name prior to any extension part.   Note: This string length is at most 8 characters plus the null terminator in spite of the 12 byte declaration.

    fileext
      A null terminated ASCII string containing the extension portion of the short DOS 8.3 alias file name.   This string may be empty if the alias has no extension.

    fileattr
      A bit field that specifies the file's attributes as defined by the following constants declared in BIOS_API.H:

        #define FJ_DA_NORMAL     0x00
        #define FJ_DA_RDONLY     0x01
        #define FJ_DA_HIDDEN     0x02
        #define FJ_DA_SYSTEM     0x04
        #define FJ_DA_VOLUME     0x08
        #define FJ_DA_DIRENT     0x10
        #define FJ_DA_ARCHIVE    0x20

    reserved
      This structure member is not used.

    filetimestamp
      The structure contains the time and date at which this file was last modified.

    filesize
      The total number of bytes in the file.

    szShort_Name
      This 14 byte buffer will hold a null terminated ASCII string containing the DOS 8.3 alias file name.   This string can be up to 12 characters in length plus a terminating null character.   (Same information as in filename and fileext presented in a single string.)  

    private_field

    Related Topics

    API function BIOS_LFN_FINDFIRST Long file name findfirst
    API function BIOS_LFN_FINDNEXT Long file name findnext
    API function BIOS_LFN_FINDDONE Long file name finddone

    Top of list
    Index page

    ServerCredentials


                
    typedef struct  tagServerCredentials{
            unsigned int idx;              //user/password array index (currently index 0 or 1 supported)
            const char * user;             //user name: max. length 20 (includes the terminating '\0' character)
            const char * password;         //password:  max. length 20 (includes the terminating '\0' character)
            unsigned int ftpAccessRights;  //ftp only:  access rights (1: write denied)
            const char * sshUserKeyFile;   //ssh only:  user key file name
    } ServerCredentials ;

    Comments

    This structure is defined in the header file BIOS_API.H.   A pointer to one of these structures in user memory is passed as the report argument to the BIOS_Set_ServerCredentials() API.


    Top of list
    Index page


    End of document