Previous: libefi, Up: Libraries

5.2 libefi-fshelp: File System Help Library

The `libefi-fshelp' library can be used by drivers that want to implement the `simple file system' protocol. The library presents a complete interface, but communicates with the file system backend through a minimal API. The interface is defined in the gnu/efi/util/fshelp.h header.

The file system backend defines a type `efi_fshelp_node_t' that represents a node in the file system. The type is fully opaque to the library. Nodes are reference counted. The library can at any time obtain an extra reference by calling the reference operation on the node, or release a reference by invoking release. It is up to the file system implementation to maintain references.

— Function: efi_status_t efi_fshelp_install_protocol_interface (efi_handle_t controller, efi_fshelp_t *fshelp, struct efi_fshelp_ops *ops)

Install all the protocol interfaces that the library defines on the controller specified by controller. fshelp is the fshelp instance that will be used through out the lifetime of the protocols. ops is the file system backend operations vector.

The efi_fshelp_ops vector contains the following operations:

— fshelp Operation: efi_status_t mount (efi_fshelp_t *fshelp, efi_fshelp_node_t **root)

Try to mount file system and return a reference to node in *root.

— fshelp Operation: void reference (efi_fshelp_node_t *node)

Obtain reference to node specified by node.

— fshelp Operation: void release (efi_fshelp_node_t *node)

Release reference to node specified by node, possible destroy it.

— fshelp Operation: efi_status_t getinfo (efi_fshelp_node_t *node, efi_file_info_t *info)

Retreive information about the node node and store it in the buffer specified by info. The backend may in turn cache the information for higher performance.

— fshelp Operation: efi_status_t setinfo (efi_fshelp_node_t *node, efi_file_info_t *info)

Set information about the node node given the information in info.

— fshelp Operation: efi_status_t readdir (efi_fshelp_node_t *dir, efi_uint64_t *fpos, efi_fshelp_node_t **nodep, efi_char16_t **namep)

Read a directory entry at the position specified by *fpos from node dir. If no more directory entries could be read, the operation should return EFI_NOT_FOUND. A reference to the node in the read directory entry is returned in *nodep, and the name of the entry in *namep. The caller is resposible for releasing the reference to *nodep and freeing the memory of *namep. The position *fpos should be updated on a successful read.

— fshelp Operation: efi_status_t read (efi_fshelp_node_t *node, efi_uint64_t fpos, efi_uint_t *size, void *buffer)

Read data from the node node at position given by fpos. The amount of data to read is determined by *size, which will be updated with the actual amount of data read on return. On return, if *size is zero there is no more data to read. The data will be read into buffer buffer.

The library also implements a set of helper functions that can be used to more easily implement some of the fshelp operations.

— Function: efi_status_t efi_fshelp_read_helper (efi_fshelp_node_t *node, efi_fshelp_read_hook_t read, void *read_data, efi_uint64_t pos, efi_uint_t *size, void *buffer, efi_fshelp_block_hook_t block, efi_uint64_t filesize, int log2blocksize)

Read *size bytes from the node node into the buffer buffer, beginning with the block pos. read hook is used to read disk blocks. read_data will be passed to the hook as the first argument. block hook is used to translate file blocks to disk blocks. The file is FILESIZE bytes big and the blocks have a size of log2blocksize (in log2, units of 512 bytes blocks).