Xenomai API  2.6.5
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:

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:

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.

Function Documentation

void xnvfile_destroy ( struct xnvfile *  vfile)

Removes a virtual file entry.

Parameters
vfileA 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
inputA pointer to the input descriptor passed to the store() handler.
dataThe address of the destination buffer to copy the input data to.
sizeThe 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
inputA pointer to the input descriptor passed to the store() handler.
valpThe 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
inputA pointer to the input descriptor passed to the store() handler.
sThe address of the destination string buffer to copy the input data to.
maxlenThe 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
nameThe name which should appear in the pseudo-filesystem, identifying the vdir entry.
vdirA pointer to the virtual directory descriptor to initialize.
parentA 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
fromThe name which should appear in the pseudo-filesystem, identifying the vlink entry.
toThe target file name which should be referred to symbolically by name.
vlinkA pointer to the virtual link descriptor to initialize.
parentA 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
nameThe name which should appear in the pseudo-filesystem, identifying the vfile entry.
vfileA 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
parentA 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
nameThe name which should appear in the pseudo-filesystem, identifying the vfile entry.
vfileA 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
parentA 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.