DumpFS

This is the source code to 32-bit DUMPFS.IFS. Here is some developer information about the resuse of this code in your own driver. Use of this source code is entirely at your own risk. This source code has not been widely tested. You will need WATCOM (for the C code and linking) plus ALP.EXE (from the OS/2 toolkit, for the ASM code) plus the DDK (for some header files) in order to build this driver. expsym.asm: this file holds a few variables that you will need to adjust for your own driver. It contains "FS_NAME" which effectively is the name of the file system as it will be known to OS/2. It contains "FS_ATTRIBUTE" and "FS32_ATTRIBUTE" which are the file system attributes. Make sure you set these two variables to the same value. The possible atttribute values are listed in the file as "FSA_...". It contains "FS_MPSAFEFLAGS2" which are additional file system attributes relating to SMP. You would normally leave these attributes as set. What this implies is that your FSD can be called simulatenously by multiple processes and is entirely responsible to properly serializing these accesses. On the other hand, handing over this responsibility from the kernel to the FSD can significantly improve overall system performance. If you wanted the kernel to handle all serialization, you would set "FS_MPSAFEFLAGS2" to 0. thunks.asm: in general, this code is expecting the use of the Watcom toolchain (compilers and linker) as it expects certain segment names which might differ from what VAC or GCC uses. in general, there is very little need to change this file. The bulk can remain unchanged. It contains all necessary thunking code so that the FSD can export the necessary 16-bit entry points to be called by the OS/2 kernel while internally thunking to 32-bit so that the bulk of the FSD code can be written in 32-bit. It was gleaned from the OPENJFS code but has one speciality: all PSZ (zero terminated string) variables (which basically are filenames and pathnames passed to the FSD) are passed unthunked as 16-bit pointers because that in turn will allow to use the 32-bit file system helper functions (FSH32_...) from the 32-bit code. See the readme.txt for the 32-bit FS Helper functions of why you cannot easily pass 32-bit pointers to the FS Helper functions. If you need a 32-bit pointer, you can just use "KernSelToFlat" to get the 32-bit pointer from the 16-bit pointer The only function that is not thunked to 32-bit is "FS_INIT" because this function is called from Ring-3 on system start and therefore has some special limitations that makes it not well suited to be thunked. Therefore, source file "init.c16" was created that will contain the necessary init code and that needs to be compiled with a 16-bit compiler. See also the makefile. Then, this file contains helpful functions that you might want to use mostly unchanged: "Ring3Init": called from FS_INIT that executes in Ring3, this function will save a pointer to the global info seg. This pointer is used by the trace functions, see following. This function only needs to be called once "TraceArg16": allows static tracing of arguments passed along with the function call. You will need to specify in "numBytes" the overall length of the arguments that you pass to this function. The major trace code selected is DUMPFS_TRACE_MAJOR (=255) and you will likely adapt this to your own value. Only callable from 16-bit code (FS_INIT, for example) "Trace16": works much like "TraceArg16" but saves a memory block instead of individual arguments passed to it Only callable from 16-bit code (FS_INIT, for example) "Ring0Init": called from FS_MOUNT and FS_FSCTL, this function will do the necessary setup for function "KernDSFlatToSel" to work, see further below. This function will protect itself from being called multiple times so that you can safely invoke it from FS_MOUNT and FS_FSCTL (which you will need as either one or the other will be the first function called). The reason why this setup cannot be done from "Ring3Init" is because it requires the code to execute in Ring0 as it is using some protected instructions that cannot be executed from Ring3 "TraceArg32": the same as "TraceArg16" but callable from 32-bit code "Trace32": the same as "Trace16" but callable from 32-bit code "KernDSFlatToSel": will convert a 32-bit pointer to a variable in the default data segment to a 16-bit pointer (so that pointer can for example be used with the FSH32_... helper functions). Please note that unless you take specific action, all declared global and static variables of the driver will go into the default data segment but you will only be able to access the first 64 kByte of that data from 16-bit code (from FS_INIT, for example). However, 32-bit code will be able to access all data in the default data segment. Please note that the code is expecting the WATCCOM segment name for the default data segment, therefore you would need to adjust "Ring0Init" if you wanted to use this code from say VAC or GCC. "KernSSFlatToSel": will convert a 32-bit pointer to a variable on the stack to a 16-bit pointer (so that pointer can for example be used with the FSH32_... helper functions). Please note that in general, the stacksize for a FSD is VERY limited so you should NEVER put large amounts of data on the stack. ifs.c: this file contains all 32-bit code and effectively implements all of the functionality of the FSD. It would be a very good idea to create an individual source file for each function ("FS32_ATTRIBUTE", "FS32_MOUNT", etc.) but due to lack of time I have jammed everything into one source file because DUMPFS has only very limited functionality. It will occasionally strike you as odd as sometimes "KernCopyIn" and "KernCopyOut" functions are used to copy in/out data from/to the kernel instead of doing a simple "memcpy". The reason is that "KernCopyIn" and "KernCopyOut" contain additional checking for accessability of the memory copy from ("KernCopyIn") or copied to ("KernCopyOut") in order to prevent a trap in the FSD if the memory is inaccessible. Instead, these functions will return with error code ERROR_PROTECTION_VIOLATION. This is done because a trap in Ring0 will lead to a complete system stop. The IFS specification (see FS32Helper readme.txt of where to obtain that from) will give you information what addresses you can expect to be valid or not. I added comments to the code that give you a clue of things to consider for implementation. init.c16: this file contains all code for the FS_INIT function. As explained earlier, this is a 16-bit code file and needs to be compiled with a 16-bit compiler. Because the code is executed in Ring3, you can use some functions like DosPutMessage to write a message to screen (on bootup). dumpfs.tsf: this trace source file contains dynamic tracepoint and also formatting information for the OS/2 tracing utility (TRACEFMT.EXE) note that initially I started to add static tracepoints to the code ("TraceArg16","Trace16","TraceArg32","Trace32") but it turned out that specifying dynamic tracepoints was simpler and did not require any code to be added. The drawback of dynamic tracing is that you cannot trace anything that happens during system start because it takes manual user interaction to enable dynamic tracing. If you decide for static tracing, please be aware that that requires static coding of minor trace codes which means that in the trace source file you will need to give each tracepoint a minor trace code and make that match to the minor trace code that you use on invocation of the trace function. See the TRCUST documentation. You can enable tracing for DUMPFS.IFS by specifying "trace ON DUMPFS" from the commandline.