Virtual file services

Collaboration diagram for Virtual file services:

Files
file	vfile.h
	This file is part of the Xenomai project.

Data Structures
struct	xnvfile_lock_ops
	Vfile locking operations. More...
struct	xnvfile_regular_ops
	Regular vfile operation descriptor. More...
struct	xnvfile_regular_iterator
	Regular vfile iterator. More...
struct	xnvfile_snapshot_ops
	Snapshot vfile operation descriptor. More...
struct	xnvfile_rev_tag
	Snapshot revision tag. More...
struct	xnvfile_snapshot
	Snapshot vfile descriptor. More...
struct	xnvfile_snapshot_iterator
	Snapshot-driven vfile iterator. More...

Functions
int	xnvfile_init_snapshot (const char *name, struct xnvfile_snapshot *vfile, struct xnvfile_directory *parent)
	Initialize a snapshot-driven vfile. More...
int	xnvfile_init_regular (const char *name, struct xnvfile_regular *vfile, struct xnvfile_directory *parent)
	Initialize a regular vfile. More...
int	xnvfile_init_dir (const char *name, struct xnvfile_directory *vdir, struct xnvfile_directory *parent)
	Initialize a virtual directory entry. More...
int	xnvfile_init_link (const char *from, const char *to, struct xnvfile_link *vlink, struct xnvfile_directory *parent)
	Initialize a virtual link entry. More...
void	xnvfile_destroy (struct xnvfile *vfile)
	Removes a virtual file entry. More...
ssize_t	xnvfile_get_blob (struct xnvfile_input *input, void *data, size_t size)
	Read in a data bulk written to the vfile. More...
ssize_t	xnvfile_get_string (struct xnvfile_input *input, char *s, size_t maxlen)
	Read in a C-string written to the vfile. More...
ssize_t	xnvfile_get_integer (struct xnvfile_input *input, long *valp)
	Evaluate the string written to the vfile as a long integer. More...

Variables
struct xnvfile_directory	nkvfroot
	Xenomai vfile root directory. More...
struct xnvfile_directory	nkvfroot
	Xenomai vfile root directory. More...

Detailed Description

Virtual files provide a mean to export Xenomai object states to user-space, based on common kernel interfaces. This encapsulation is aimed at:

• supporting consistent collection of very large record-based output, without encurring latency peaks for undergoing real-time activities.
• in the future, hiding discrepancies between linux kernel releases, regarding the proper way to export kernel object states to userland, either via the /proc interface or by any other mean.

This virtual file implementation offers record-based read support based on seq_files, single-buffer write support, directory and link handling, all visible from the /proc namespace.

The vfile support exposes four filesystem object types:

• snapshot-driven file (struct xnvfile_snapshot). This is commonly used to export real-time object states via the /proc filesystem. To minimize the latency involved in protecting the vfile routines from changes applied by real-time code on such objects, a snapshot of the data to output is first taken under proper locking, before the collected data is formatted and sent out in a lockless manner.

Because a large number of records may have to be output, the data collection phase is not strictly atomic as a whole, but only protected at record level. The vfile implementation can be notified of updates to the underlying data set, and restart the collection from scratch until the snapshot is fully consistent.

• regular sequential file (struct xnvfile_regular). This is basically an encapsulated sequential file object as available from the host kernel (i.e. seq_file), with a few additional features to make it more handy in a Xenomai environment, like implicit locking support and shortened declaration for simplest, single-record output.
• virtual link (struct xnvfile_link). This is a symbolic link feature integrated with the vfile semantics. The link target is computed dynamically at creation time from a user-given helper routine.
• virtual directory (struct xnvfile_directory). A directory object, which can be used to create a hierarchy for ordering a set of vfile objects.

Function Documentation

void xnvfile_destroy

(

struct xnvfile *

vfile

)

Removes a virtual file entry.

Parameters

vfile

A pointer to the virtual file descriptor to remove.

ssize_t xnvfile_get_blob	(	struct xnvfile_input *	input,
		void *	data,
		size_t	size
	)

Read in a data bulk written to the vfile.

When writing to a vfile, the associated store() handler from the snapshot-driven vfile or regular vfile is called, with a single argument describing the input data. xnvfile_get_blob() retrieves this data as an untyped binary blob, and copies it back to the caller's buffer.

Parameters

input	A pointer to the input descriptor passed to the store() handler.
data	The address of the destination buffer to copy the input data to.
size	The maximum number of bytes to copy to the destination buffer. If size is larger than the actual data size, the input is truncated to size.

Returns

The number of bytes read and copied to the destination buffer upon success. Otherwise, a negative error code is returned:

• -EFAULT indicates an invalid source buffer address.

Referenced by xnvfile_get_integer(), and xnvfile_get_string().

ssize_t xnvfile_get_integer	(	struct xnvfile_input *	input,
		long *	valp
	)

Evaluate the string written to the vfile as a long integer.

When writing to a vfile, the associated store() handler from the snapshot-driven vfile or regular vfile is called, with a single argument describing the input data. xnvfile_get_integer() retrieves and interprets this data as a long integer, and copies the resulting value back to valp.

The long integer can be expressed in decimal, octal or hexadecimal bases depending on the prefix found.

Parameters

input	A pointer to the input descriptor passed to the store() handler.
valp	The address of a long integer variable to receive the value.

Returns

The number of characters read while evaluating the input as a long integer upon success. Otherwise, a negative error code is returned:

• -EINVAL indicates a parse error on the input stream; the written text cannot be evaluated as a long integer.
• -EFAULT indicates an invalid source buffer address.

References xnvfile_get_blob().

ssize_t xnvfile_get_string	(	struct xnvfile_input *	input,
		char *	s,
		size_t	maxlen
	)

Read in a C-string written to the vfile.

When writing to a vfile, the associated store() handler from the snapshot-driven vfile or regular vfile is called, with a single argument describing the input data. xnvfile_get_string() retrieves this data as a null-terminated character string, and copies it back to the caller's buffer.

Parameters

input	A pointer to the input descriptor passed to the store() handler.
s	The address of the destination string buffer to copy the input data to.
maxlen	The maximum number of bytes to copy to the destination buffer, including the ending null character. If maxlen is larger than the actual string length, the input is truncated to maxlen.

Returns

The number of characters read and copied to the destination buffer upon success. Otherwise, a negative error code is returned:

• -EFAULT indicates an invalid source buffer address.

References xnvfile_get_blob().

int xnvfile_init_dir	(	const char *	name,
		struct xnvfile_directory *	vdir,
		struct xnvfile_directory *	parent
	)

Initialize a virtual directory entry.

Parameters

name	The name which should appear in the pseudo-filesystem, identifying the vdir entry.
vdir	A pointer to the virtual directory descriptor to initialize.
parent	A pointer to a virtual directory descriptor standing for the parent directory of the new vdir. If NULL, the /proc root directory will be used. /proc/xenomai is mapped on the globally available nkvfroot vdir.

Returns

0 is returned on success. Otherwise:

• -ENOMEM is returned if the virtual directory entry cannot be created in the /proc hierarchy.

int xnvfile_init_link	(	const char *	from,
		const char *	to,
		struct xnvfile_link *	vlink,
		struct xnvfile_directory *	parent
	)

Initialize a virtual link entry.

Parameters

from	The name which should appear in the pseudo-filesystem, identifying the vlink entry.
to	The target file name which should be referred to symbolically by name.
vlink	A pointer to the virtual link descriptor to initialize.
parent	A pointer to a virtual directory descriptor standing for the parent directory of the new vlink. If NULL, the /proc root directory will be used. /proc/xenomai is mapped on the globally available nkvfroot vdir.

Returns

0 is returned on success. Otherwise:

• -ENOMEM is returned if the virtual link entry cannot be created in the /proc hierarchy.

int xnvfile_init_regular	(	const char *	name,
		struct xnvfile_regular *	vfile,
		struct xnvfile_directory *	parent
	)

Initialize a regular vfile.

Parameters

name	The name which should appear in the pseudo-filesystem, identifying the vfile entry.
vfile	A pointer to a vfile descriptor to initialize from. The following fields in this structure should be filled in prior to call this routine:

• .privsz is the size (in bytes) of the private data area to be reserved in the vfile iterator. A NULL value indicates that no private area should be reserved.
• entry.lockops is a pointer to a lockingdescriptor", defining the lock and unlock operations for the vfile. This pointer may be left to NULL, in which case no locking will be applied.
• .ops is a pointer to an operation descriptor.

Parameters

parent

A pointer to a virtual directory descriptor; the vfile entry will be created into this directory. If NULL, the /proc root directory will be used. /proc/xenomai is mapped on the globally available nkvfroot vdir.

Returns

0 is returned on success. Otherwise:

• -ENOMEM is returned if the virtual file entry cannot be created in the /proc hierarchy.

int xnvfile_init_snapshot	(	const char *	name,
		struct xnvfile_snapshot *	vfile,
		struct xnvfile_directory *	parent
	)

Initialize a snapshot-driven vfile.

Parameters

name	The name which should appear in the pseudo-filesystem, identifying the vfile entry.
vfile	A pointer to a vfile descriptor to initialize from. The following fields in this structure should be filled in prior to call this routine:

• .privsz is the size (in bytes) of the private data area to be reserved in the vfile iterator. A NULL value indicates that no private area should be reserved.
• .datasz is the size (in bytes) of a single record to be collected by the next() handler from the operation descriptor.
• .tag is a pointer to a mandatory vfile revision tag structure (struct xnvfile_rev_tag). This tag will be monitored for changes by the vfile core while collecting data to output, so that any update detected will cause the current snapshot data to be dropped, and the collection to restart from the beginning. To this end, any change to the data which may be part of the collected records, should also invoke xnvfile_touch() on the associated tag.
• entry.lockops is a pointer to a lockingdescriptor", defining the lock and unlock operations for the vfile. This pointer may be left to NULL, in which case the operations on the nucleus lock (i.e. nklock) will be used internally around calls to data collection handlers (see operation descriptor).
• .ops is a pointer to an operation descriptor.

Parameters

parent

A pointer to a virtual directory descriptor; the vfile entry will be created into this directory. If NULL, the /proc root directory will be used. /proc/xenomai is mapped on the globally available nkvfroot vdir.

Returns

0 is returned on success. Otherwise:

• -ENOMEM is returned if the virtual file entry cannot be created in the /proc hierarchy.

References xnvfile_snapshot_ops::store.

Variable Documentation

struct xnvfile_directory nkvfroot

Xenomai vfile root directory.

This vdir maps the /proc/xenomai directory. It can be used to create a hierarchy of Xenomai-related vfiles under this root.

struct xnvfile_directory nkvfroot

Xenomai vfile root directory.

This vdir maps the /proc/xenomai directory. It can be used to create a hierarchy of Xenomai-related vfiles under this root.