SVR5

mdi_open_file(D3mdi)

mdi_open_file -- open regular file for reading

Synopsis

   #include <sys/types.h>
   #include <sys/stream.h>
   #include <sys/stropt.h>
   #include <sys/mdi.h>
   #include <sys/ddi.h>
   
   int mdi_open_file(const char *modname, const char *path,
                     size_t *filesizep, mdi_file_t *handle);

Description

mdi_open_file( ) opens a regular file, including larger files such as message catalogs, in the file system for reading.

Arguments

modname: Pointer to NULL terminated string that contains the drivers module name.
path: Pointer to NULL terminated string that contains the path to the file to be opened, including the file name relative to the driver's pack.d directory in the link kit. For example, if path is set to file1 and modname is mod1, the file referenced is /etc/conf/pack.d/mod1/file1.
filesizep: Size of the file, in bytes, is returned here.
handle: Handle to be used for all future references to the file is returned here. mdi_file_t is defined in the mdi.h header file.

Return values

EINVAL: Either modname or path were NULL.
EAGAIN: Could not obtain the memory required to build the internal control structure needed to open the file.
ENOENT: File was not found at the path specified or was not a regular file.
EFBIG: File is too big (greater than the size of a size_t)

Usage

This function allows drivers to access download code or message catalogs directly from the driver. It is typically called from the driver's _load(D2mdi) entry point routine. You must call the mdi_read_file(D3mdi) function to read the file and the mdi_close_file(D3mdi) function to close the file and release the buffer obtained after the information is downloaded.

These functions enable you to obtain download firmware or a driver's message catalog from user space without recompiling the driver for different locales. You can omit the CONFIG_CMDS, PRE_SCRIPT, and POST_SCRIPT variables from the driver's bcfg(DSP/4dsp) file if you use this technique in the driver source code, although the files must still be listed in the EXTRA_FILES variable.

Context and synchronization

Blockable context at a time when it is safe to lower the system interrupt priority (ipl) to plbase.

Hardware applicability

All

Version applicability

mdi: 2, 2.1

Differences between versions

In MDI version 2, the syntax of mdi_open_file( ) was

   int mdi_open_file(char *pathname, uchar_t **filebuffer,
                     int *bufferlength);

The arguments were defined as:

pathname: absolute pathname of the file in the filesystem. Typically, this file is located in the driver's subdirectory to the /etc/conf/pack.d directory where idinstall puts such files, but it can be located elsewhere.
filebuffer: start of the buffer that contains the contents of the file. This buffer is located in the first 16MB of memory, does not need to be page aligned, and does not need to be physically contiguous.
bufferlength: size of the file, in bytes.

This function is not supported in MDI on SCO OpenServer systems.

References

mdi_close_file(D3mdi) mdi_read_file(D3mdi)

Examples

This code fragment illustrating the use of mdi_open_file( ) and mdi_close_file(D3mdi) is excerpted from the e3D driver. This fragment demonstrates how a driver can open a file that resides in the filesystem. idinstall handles firmware.o and msg.o files as part of the DSP, putting them in your driver's subdirectory in the /etc/conf/pack.d directory. mdi_open_file( ) can use this pathname (ignoring idbuild's $ROOT) or use some other location, as long as it is an absolute pathname. This code fragment does not need to do any of this, but illustrates how it would be done.

   e3D_cat_file(char *pathname)
   {
   	unsigned char *filebuffer;
   	int ret,loop,bufferlength;
   
   	ret=mdi_open_file(pathname, &filebuffer, &bufferlength);
   	if (ret) {
   		/* some sort of problem encountered:
   		 * ENOENT: null path, not absolute, lookupname failed,
   		 *         not regular file,
   		 * EACCES: couldn't open file, couldn't stat file,
   		 * EFBIG:  file is 0 bytes or too big (> 64K)
   		 * ENOMEM: no memory available to hold buffer to file
   		 * others are possible, these are the main ones
   		 * cmn_err will have already been called by mdi_open_file.
   		 */
   		cmn_err(CE_NOTE,"e3D_cat_file: couldn't open %s\n",pathname);
   		return;
   	}
   	/* filebuffer now points to the contents of the file
   	 * bufferlength has the size of the file
   	 * you would pump the contents of the file to the firmware here.
   	 * --->Note that if something goes wrong past this point we must still
   	 * call mdi_close_file to close the file and release the memory!<----
   	 * for demonstration purposes we'll just display the file on the
   	 * console.
   	 */
   	cmn_err(CE_NOTE,
   		"%s is %d bytes long and contains the following text:\n",
   		pathname, bufferlength);
   	for (ret=0; ret<bufferlength; ret++) {
   		cmn_err(CE_CONT,"%c",filebuffer[ret]);
   	}
   	cmn_err(CE_CONT,"\n");
   

   	/* close the file we previously opened */
   	mdi_close_file(filebuffer);
   

   	return;
   }