@CHIP-RTOS - Data Structures used in BIOS API

Data Structures

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

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

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

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.

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.

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

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

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

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