Cs 345 Project 6 - Fat

FAT File Management System CS 345 - Project Six

Purpose File management is a central component to most applications. With the exception of perhaps real-time applications, the input and output of an application is via a file. Files have a life outside of any individual application and provide a medium for later access by the user or by other programs. Typically, an operating system implements a file management system with a set of utility programs that run as privileged applications. In this project, you will add a MS-DOS® FAT-12 file manager to your operating system that will enable you to traverse file directories, read/write/seek file data, and execute LC-3 program files. Project Six is designed to help the student:      

understand the organization of a file management system. understand file allocation tables (FAT). understand FAT directory structures and cluster chains. understand a boot sector. understand file system buffering, basic file I/O, file descriptors, and file pointers. understand file access modes and learn how to modify file allocation tables (FAT), directory structures and cluster chains.

Project Requirements The following are important guidelines for programming the FAT FMS assignment: 1) RAM Disk Image: A FAT-12 disk image is loaded into a RAM disk (memory array) using the shell mount command. The RAM disk is divided into 2849 sectors, each being 512 bytes in length. The file allocation tables (FAT1 and FAT2) are held in separate memory arrays. All memory accesses to the RAM disk array must be made using the following read/write sector functions: a. int fmsReadSector(void* buffer, int sectorNumber)  Read into buffer buffer RAM disk sector number sectorNumber. Sectors are 512 bytes.  Return 0 for success; otherwise, return an error number. b. int fmsWriteSector(void* buffer, int sectorNumber)  Write 512 bytes from memory pointed to by buffer to RAM disk sector sectorNumber.  Return 0 for success; otherwise, return an error number. 2) RAM Disk Files and Directories: A FAT-12 file system specifies how files are named, accessed, and stored in your RAM disk image. Your program will maintain a “current directory” variable (cDir in the task control block) which points to the start cluster of the current working directory. You must be able to navigate hierarchal directories using the cd and dir shell commands. Short file and directory names can be assumed to be at most 8 characters long, with an optional 1-3 character extension (filename is separated from the extensions by a dot [.]).

BYU, CS 345

Project Six – FAT

Page 1/10

3)

FAT Directory and Cluster Chains: Project Six is divided into two parts. The first part deals with disk directories and file navigation. You will need to implement the following API‟s: (Do NOT change these API‟s.) a. int fmsChangeDir(char* dirName)  The fmsChangeDir function changes the current directory to the subdirectory specified by the string argument dirName.  You will only need to handle moving up or down a directory.  Verify that dirName is a valid directory name in the current directory.  Return a 0 for success; otherwise return error number. b. int fmsGetNextDirEntry(int* dirNum, char* mask, DirEntry* dirEntry, int cDir)  The fmsGetNextDirEntry function reads the next directory entry from the cDir directory as specified by dirNum, into the 32 byte dirEntry struct. (See Directory Structure below.)  The dirNum parameter is passed by reference and set to 0 for the first entry. Each call to fmsGetNextDirEntry updates this value for subsequent calls. dirNum acts as a directory iterator and holds entry index state in a local task variable and not in the FMS subsystem.  The parameter mask is a selection string. If null, return next directory entry. Otherwise, use the mask string to select the next directory entry. An „*‟ is a wild card for any length string. A „?‟ is a wild card for any single character. Any other character must match exactly. (See mask description below.)  Return 0 for success; otherwise, return the error number.

4)

C File Management Functions: The second part of Project Six deals with basic file I/O operations. You will need to implement the following C functions in your File Management System: (Again, do NOT change the API‟s.): a. int fmsCloseFile(int fileDescriptor)  The fmsCloseFile function closes the open file specified by fileDescriptor.  The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.  Return a 0 for success; otherwise return error number. b. int fmsDefineFile(char* filename, int attribute)  If attribute equals 0x10, then a new sub-directory file, named directoryName, is created in the current directory. One cluster is allocated to the file with new directory entries “.” and “..”.  Else, a new file, named filename, is created in the current directory with file attribute equal to attribute. No clusters are allocated to that file.  Return 0 for success; otherwise, return the error number. c. int fmsDeleteFile(char* fileName)  This function deletes the file/directory file named fileName from the current directory.  The file name in the directory entry should be marked with a 0xe5 as the first character and the chained clusters in FAT 1 reallocated (set to 0).  A directory file must not have any valid file or directory entries.  Return 0 for success; otherwise, return the error number.

d. int fmsOpenFile(char* fileName, int rwMode)  This function opens the file named fileName for access as specified by rwMode.  The open mode rwMode is defined as follows: 0 - Read access only. BYU, CS 345 Project Six – FAT File Management System

Page 2/10

  

The file pointer is initialized to the beginning of the file. Writing to this file is not allowed. 1 - Write access only. The file pointer is initialized to the beginning of the file. Reading from this file is not allowed. 2 - Append access. The file pointer is moved to the end of the file. Reading from this file is not allowed. 3 - Read/Write access. The file pointer is initialized to the beginning of the file. Both read and writing to the file is allowed. A maximum of 32 files may be open at any one time. Return an error if the file does not exist, already open, or too many files are open. If successful, return a file descriptor that is used in calling subsequent file handling functions; otherwise, return the error number.

e. int fmsReadFile(int fileDescriptor, char* buffer, int nBytes)  This function reads nBytes bytes from the open file specified by fileDescriptor into memory pointed to by buffer.  The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.  After each read, the file pointer is advanced.  Return the number of bytes successfully read (watch for the end of file), or the error number for failure (error numbers are negative). (If you are already at the end of the file, return 0 bytes successfully read.) f. int fmsSeekFile(int fileDescriptor, int index)  This function changes the current file pointer of the open file specified by fileDescriptor to the new file position specified by index.  The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.  The file position may not be positioned beyond the end of the file.  Return the new position in the file if successful; otherwise, return the error number. g. int fmsWriteFile(int fileDescriptor, char* buffer, int nBytes)  This function writes nBytes bytes to the open file specified by fileDescriptor from memory pointed to by buffer.  The fileDescriptor was returned by fmsOpenFile and is an index into the open file table.  Writing is always "overwriting" not "inserting" in the file and always writes forward from the current file pointer position.  Return the number of bytes successfully written; otherwise, return the error number. 5) Validation: Your completed file management system must be able to pass a disk validation program (chkdsk) and a final stress test (final). The DOS function chkdsk analyzes a FAT-12 disk and reports any problems. (See description below.) The final program has six steps that will test various implementations of your file manager and must be executed in order. These tests include the creation and deletion of a large number of files and directories, opening and closing a maximum number of files, random access within files using the read, seek, and write primitives, and testing the various modes of opening files including read-only, write, read/write, and append.

BYU, CS 345

Project Six – FAT File Management System

Page 3/10

About DOS File Names A DOS 8.3 file name is composed of two parts: a name, which can be up to eight characters long, and an optional extension, which can be up to three characters long. The name and extension are separated by a period. A file name may not begin with a period. Extensions are typically not added to directory names because it makes discerning them from filenames difficult. The extension is DOS' way of determining which of the four basic functions a file performs: executable (.exe or .com), support (.ini, .cgf, or .dll), data (.doc, .txt, .xls, .dbf, and .dxf), and batch (.bat). In general, DOS filenames use only letters and numerals. Upper and lower case letters are considered identical. In addition, the following symbols can be used in file names: `~!@#$%^&()_-{}' Valid DOS file names RESULTS.TXT SEARCH.#1 READ.ME! MY.DOC A.A A {MYFILE}

Invalid DOS file names MYRESULTS.TXT SEARCH.RESULTS ONE.TWO.3 /.\

(MYRESULTS is 9 characters) (RESULTS is 7 characters) (Only use one period) (Invalid punctuation symbols)

File/Directory Masks A file name mask is used to selectively qualify directory entries. A wildcard is a special character that can fill in for missing letter(s) in file and directory names when used to add specificity to OS commands. Although there are various ways to define the syntax and semantics of a mask string, we will use the following rules:   



A mask has two parts, one for the file name and the other for the extension. If an extension mask is included, it is separated from the file mask by a period. A null file mask string qualifies all entries (regardless of extension.) An „*‟ qualifies all characters to the right and cannot be followed by any characters (other than a period and an extension mask.) There can be only one “*” per file name and/or extension mask. Thus a single “*” would select all files without an extension. A “*.*” mask would be the same as a null string and select all files with or without an extension. A „?‟ is a wild card for any single character and requires the presence of a character in the file name to qualify. It may be used multiple times in the file name and/or file extension mask. Examples:

BYU, CS 345

*.* B* ???*.C *.TXT

All files All files beginning with „B‟ and no extension All files of length at least 3 with „C‟ extension All files with “TXT” extension

Project Six – FAT File Management System

Page 4/10

Directory structure A DOS directory entry is a 32-byte struct that contains the file name, extension, time and date of last update, size of the file (in bytes), and the cluster number of the cluster of the file. File names follow the 8.3 naming standard. Time, date, startCluster, and fileSize are in little-endian format. The struct must be byte aligned. #pragma pack(push,1) typedef struct { unsigned char unsigned char unsigned char unsigned char unsigned short unsigned short unsigned short unsigned long } DirEntry; #pragma pack(pop)

/* byte align in memory (no padding) */ Name[8]; Extension[3]; Attributes; Reserved[10]; Time; Date; startCluster; fileSize;

/* file name */ /* extension */ /* holds the attributes code */ /* reserved */ /* time of last write */ /* date of last write */ /* pointer to the first cluster of the file. */ /* file size in bytes */ /* end of strict alignment */

File/Directory Deletion DOS does not immediately erase a file or directory when it is deleted. In fact, it does nothing to the clusters that contain the information (this is why it is sometimes possible to un-delete something). However, DOS does zero out the file/directory's cluster chain from the FAT table and places a special character (0xe5) in the first byte of the directory entry signaling that this entry has been deleted. You will need to do the same when a file or directory is deleted. Start with the cluster indicated in the directory entry, traverse the cluster chain, and then set each FAT entry to zero including the EOC entry. The special code 0xe5 in the first byte of a directory entry, indicates that this directory entry is free, and may be overwritten with a new entry in the future. Place this value in the first byte of the directory entry to effectively delete it (it will be the first character of the file/directory name field). When reading directory entries, ignore all entries that begin with 0xe5. When making any change to the FAT 1 table, copy the FAT 1 table to the FAT 2 table, EXCEPT when deleting a file.

Validity (chkdsk) Command The DOS function chkdsk analyzes a FAT-12 disk and reports any problems. You should use chkdsk to validate your file manager implementation. Here are some checks and error messages that the chkdsk program will look for:  

lost chains – Allocated sectors not belonging to any directory or file. cross-linked chains – two entries in the FAT table are "pointing" to the same cluster.

BYU, CS 345

Project Six – FAT File Management System

Page 5/10







invalid directory entry o invalid name – directory entries padded with zeros instead of spaces or lowercase. o invalid extended attribute handle – "reserved" field of directory entry not zeroed out. o invalid attribute – combination of attribute bits not recognizable. o invalid date – date in future (or before 2000). o invalid file size – file size impossible or file size 0 with non-zero start cluster. o invalid file start cluster – start cluster out of bounds. o zombie long name directory entry – long short names differ. invalid directory o dot/dotdot invalid – dot or dotdot entries invalid or missing. o invalid format – directory entries after “last” entry. improperly formatted disk o invalid boot sector – corrupted data or constants. o invalid fat tables – fat tables have not been or cannot be reconciled.

FMS Errors In order to use the LC-3 file programs, we must standardize on error numbers coming from the File Management System. As such, please use the following error definitions in your implementation: # -50 -51 -52 -53 -54 -55 -60 -61 -62 -63 -64 -65 -66

Error Description "Invalid File Name" "Invalid File Type" "Invalid File Descriptor" "Invalid Sector Number" "Invalid FAT Chain" "Invalid Directory" "File Already Defined" "File Not Defined" "File Already Open" "File Not Open" "File Directory Full" "File Space Full" "End-Of-File"

# -67 -68 -69 -70 -71 -72 -80 -81 -82 -83 -84 -85 -1

Error Description "End-Of-Directory" "Directory Not Found" "Can Not Delete" "Too Many Files Open" "Not Enough Contiguous Space" "Disk Not Mounted" "File Seek Error" "File Locked"" "File Delete Protected" "File Write Protected" "Read Only File" "Illegal Access" "Undefined Error

Implementation Strategy 1. Read and comprehend the MS-DOS FAT File System help document as well as Stallings, Chapter 12. 2. Comprehend these lab specs. Discuss questions with classmates, the TA‟s and/or the professor. Make sure you understand what the requirements are! 3. Design your file management system. Break the problem down into manageable parts. 4. A suggested implementation order might be: a. Begin with the shell commands cd and dir. Implement the fmsChangeDir and fmsGetNextDirEntry functions. b. Implement fmsOpenFile, fmsReadFile, and fmsCloseFile. Verify your implement using the type command. c. Implement fmsWriteFile. Verify your implement using the copy command. d. Implement fmsDefineFile, fmsDeleteFile. BYU, CS 345 Project Six – FAT File Management System Page 6/10

e. Implement fmsSeekFile and test with LC-3 decoder programs. f. Valid your completed FMS with the chkdsk and final programs.

Grading and Pass-off Your FMS I assignment is to be demonstrated in person to a TA and is outlined as follows: 1) Do the following:  Add a FAT-12 file management system to your operating system. Use an open file table, I/O buffering, file descriptors to accommodate up to 32 open files at a time.  Change your shell prompt to display the current working directory path name.  Use the following shell commands to demonstrate your file manager: (Please ask your instructor/TA for further clarification of arguments.) o cd Change directory o chkdsk Check disk o copy , Copy file o define Define file o delete Delete file o dir {<mask>} Display files in current directory o fat <#>,<s>,<e> Display FAT structure o final Test file manager o map {<mask>} Map files from current directory o mkdir Create directory o mount Initialize FAT-12 RAM disk from file o run Execute LC-3 program o sp Display bytes used/free/bad/size o type Display file o unmount Write FAT-12 RAM disk to file 2) Demonstrate that your file management system is functioning correctly. Be able to traverse the directory structure on a disk and list selected files. Be able to display file contents. Be able to copy files, create and delete files and directories, seek, read/write, and append files, and successfully execute LC-3 file programs from your RAM disk. 3) There are 20 points possible for Project 6. The grading criteria will be as follows:       

1 pt – Correctly detect invalid DOS file names where applicable. 2 pts – Successfully traverse (cd) file directories and display at the shell prompt, the full path name to the current working directory. 2 pts – Correctly display entries in the current directory (dir) using a selection mask while ignoring long file names (unless implementing bonus). 3 pts – Successfully define (define, mkdir) and delete (delete) files/directories. 3 pts – Successfully copy files using the copy command. 3 pts – Successfully execute (run) the LC-3 decoder programs (decode1.hex,…, decode9.hex) from RAM disk 4. 6 pts – Successfully validate your implementation with the chkdsk command and pass all the file management stress tests (final, p6). (Tests must be passed in consecutive order.)

BYU, CS 345

Project Six – FAT File Management System

Page 7/10

In addition to the possible 20 points, the following bonus/penalties apply:        

+2 points bonus for early pass-off (at least one day before due date.) +2 points bonus for implementing support (cd, dir) for long file names. +2 points bonus for implementing an undelete command. +2 points bonus for implementing a rename command. +2 points bonus for deleting multiple files using a file mask. +5 points bonus for implementing your file management functions as background kernel tasks that suspend the calling process until I/O operations complete. -2 points penalty for each school day late. -20 points penalty for any invalid reference to the RAM disk.

Sample Output ***NOTE: This sample may or may not reflect your results and should not be used as validation of your FMS implementation. CS345 F2008 0>>mount Mount Disk "c:/lcc/projects/disk4" System: IBM 3.3 Bytes/Sector: 512 Sectors/Cluster: 1 Reserved sectors: 1 FAT tables: 2 Max root dir entries: 224 FAT-12 sectors: 2880 FAT sectors: 9 Sectors/track: 18 Heads/volume: 2 FAT-32 sectors: 0 c:/lcc/projects/disk4:\>>final all Running Test 1... Define 128 directories... Define 64 files... Running Test 2... Open 64 files... Now is the time for all good men Running Test 3... Now is the time for all good men Running Test 4... Now is the time for all good men Running Test 5... fmsMakeDirectory("TESTDIR") fmsChangeDir("TESTDIR") Define 64 files... fmsChangeDir("..") fmsDeleteFile("TESTDIR") Can Not fmsChangeDir("TESTDIR") Delete 64 files... fmsChangeDir("..") fmsDeleteFile("TESTDIR") Running Test 6... Delete 64 files...

BYU, CS 345

to come to the aid of their country. to come to the aid of their country. to come to the aid of their country.

Delete... Good!

Project Six – FAT File Management System

Page 8/10

Delete 128 directories... Slot Name Ext Atr Size Strt Curr cDir cPID Mode Flag Indx Name:ext time date cluster size BIGDIR ----D- 11:31:40 03/31/2004 3 0 BYU ----D- 11:34:54 03/31/2004 171 0 JOKES ----D- 11:37:06 03/31/2004 800 0 LONGFI~1 ----D- 11:37:14 03/31/2004 875 0 PERSONAL ----D- 11:37:18 03/31/2004 937 0 TEMP ----D- 11:37:36 03/31/2004 1355 0 H2O.C -----A 19:00:02 02/12/2004 1380 3425 MAKE.TXT -----A 16:26:58 02/27/2004 1387 18584 CONGRATULATIONS! YOU PASS! c:/lcc/projects/disk4:\>>cd byu c:/lcc/projects/disk4:\byu>>cd cs345 c:/lcc/projects/disk4:\byu\cs345>>cd projects c:/lcc/projects/disk4:\byu\cs345\projects>>cd p6 c:/lcc/projects/disk4:\byu\cs345\projects\p6>>run decode1.hex c:/lcc/projects/disk4:\byu\cs345\projects\p6>> Load "decode1.hex" from FAT Memory loaded! PC=0x3000 Process #1 Halted at 0x313e Exit Task 1 c:/lcc/projects/disk4:\byu\cs345\projects\p6>>dir Name:ext time date cluster size . ----D- 11:35:10 03/31/2004 224 0 .. ----D- 11:35:10 03/31/2004 222 0 DECODE1.HEX -----A 11:00:58 03/31/2004 225 3630 DECODE2.HEX -----A 11:02:10 03/31/2004 233 3630 DECODE3.HEX -----A 11:02:56 03/31/2004 241 3630 DECODE4.HEX -----A 11:03:44 03/31/2004 249 3630 DECODE5.HEX -----A 11:04:14 03/31/2004 257 3630 DECODE6.HEX -----A 11:04:36 03/31/2004 265 3630 DECODE7.HEX -----A 11:05:02 03/31/2004 273 3630 DECODE8.HEX -----A 11:05:26 03/31/2004 281 3630 DECODE9.HEX -----A 11:05:48 03/31/2004 289 3630 DICT.DAT -----A 13:45:30 03/22/2004 297 4600 SECRET1.DAT -----A 13:45:30 03/22/2004 306 156 SECRET2.DAT -----A 13:45:30 03/22/2004 307 966 SECRET3.DAT -----A 13:45:30 03/22/2004 309 300 SECRET4.DAT -----A 13:45:30 03/22/2004 310 1146 SECRET5.DAT -----A 13:45:30 03/22/2004 314 660 SECRET6.DAT -----A 13:45:30 03/22/2004 316 1494 SECRET7.DAT -----A 13:45:30 03/22/2004 319 492 SECRET8.DAT -----A 13:45:30 03/22/2004 320 438 SECRET9.DAT -----A 13:45:30 03/22/2004 321 282 MAP.HEX -----A 13:11:24 03/20/2004 1563 1782 CALCUL~1.HEX -----A 14:38:18 01/27/2004 1567 6174 CRAWLER.HEX -----A 17:18:00 02/02/2004 1580 1980 MEMTEST.HEX -----A 22:09:32 02/09/2004 1584 2640 MESSAGE1.TXT -----A 15:14:44 10/01/2008 2 61 c:/lcc/projects/disk4:\byu\cs345\projects\p6>>type message1.txt Men do not fail, but often rather, they simply quit trying... c:/lcc/projects/disk4:\byu\cs345\projects\p6>>final all Running Test 1... Define 128 directories... Define 64 files... Running Test 2... Open 64 files... Now is the time for all good men to come to the aid of their country.

BYU, CS 345

Project Six – FAT File Management System

Page 9/10

Running Test 3... Now is the time for all good men to come to the aid of their country. Running Test 4... Now is the time for all good men to come to the aid of their country. Running Test 5... fmsMakeDirectory("TESTDIR") fmsChangeDir("TESTDIR") Define 64 files... fmsChangeDir("..") fmsDeleteFile("TESTDIR") Can Not Delete... Good! fmsChangeDir("TESTDIR") Delete 64 files... fmsChangeDir("..") fmsDeleteFile("TESTDIR") Running Test 6... Delete 64 files... Delete 128 directories... Slot Name Ext Atr Size Strt Curr cDir cPID Mode Flag Indx Name:ext time date cluster size . ----D- 11:35:10 03/31/2004 224 0 .. ----D- 11:35:10 03/31/2004 222 0 DECODE1.HEX -----A 11:00:58 03/31/2004 225 3630 DECODE2.HEX -----A 11:02:10 03/31/2004 233 3630 DECODE3.HEX -----A 11:02:56 03/31/2004 241 3630 DECODE4.HEX -----A 11:03:44 03/31/2004 249 3630 DECODE5.HEX -----A 11:04:14 03/31/2004 257 3630 DECODE6.HEX -----A 11:04:36 03/31/2004 265 3630 DECODE7.HEX -----A 11:05:02 03/31/2004 273 3630 DECODE8.HEX -----A 11:05:26 03/31/2004 281 3630 DECODE9.HEX -----A 11:05:48 03/31/2004 289 3630 DICT.DAT -----A 13:45:30 03/22/2004 297 4600 SECRET1.DAT -----A 13:45:30 03/22/2004 306 156 SECRET2.DAT -----A 13:45:30 03/22/2004 307 966 SECRET3.DAT -----A 13:45:30 03/22/2004 309 300 SECRET4.DAT -----A 13:45:30 03/22/2004 310 1146 SECRET5.DAT -----A 13:45:30 03/22/2004 314 660 SECRET6.DAT -----A 13:45:30 03/22/2004 316 1494 SECRET7.DAT -----A 13:45:30 03/22/2004 319 492 SECRET8.DAT -----A 13:45:30 03/22/2004 320 438 SECRET9.DAT -----A 13:45:30 03/22/2004 321 282 MAP.HEX -----A 13:11:24 03/20/2004 1563 1782 CALCUL~1.HEX -----A 14:38:18 01/27/2004 1567 6174 CRAWLER.HEX -----A 17:18:00 02/02/2004 1580 1980 MEMTEST.HEX -----A 22:09:32 02/09/2004 1584 2640 MESSAGE1.TXT -----A 15:14:44 10/01/2008 2 61 CONGRATULATIONS! YOU PASS! c:/lcc/projects/disk4:\byu\cs345\projects\p6>>

BYU, CS 345

Project Six – FAT File Management System

Page 10/10