Base API

The libnfb is userspace library, which allows to do the basic operations over NFB cards.

Init and deinit functions

struct nfb_device *nfb_open(const char *path)

Open the NFB device.

This is the initialization function, which must be called before other library functions. Upon successful completion, the returned value is a NFB device handle to be passed to other functions.

Parameters:

path – [in] Path to the NFB device file

Returns:

NFB device handle on success
NULL on error (errno is set)

void nfb_close(struct nfb_device *dev)

Close the NFB device.

Call this function to finish the work with NFB device and cleanup. The handle passed to this function can not be used further and you must ensure to close that all other opened subhandles (e.g. by nfb_comp_open) are closed.

Parameters:: dev – [in] NFB device handle

Device tree functions

const void *nfb_get_fdt(const struct nfb_device *dev)

Retrieve NFB device Device Tree description.

Parameters:

dev – [in] NFB device handle

Returns:

Device Tree (in FDT format) on success
NULL on error

int nfb_comp_count(const struct nfb_device *dev, const char *compatible)

Return count of components present in firmware.

This function goes through FDT and counts all nodes with matching ‘compatible’ property.

Parameters:

dev – [in] NFB device handle
compatible – [in] Component ‘compatible’ string

Returns:

Non-negative number of components on success
Negative error code on error

int nfb_comp_find(const struct nfb_device *dev, const char *compatible, unsigned index)

Return FDT offset of a specific component.

This function goes through FDT and finds N-th node with matching ‘compatible’ property.

Parameters:

dev – [in] NFB device handle
compatible – [in] Component ‘compatible’ string
index – [in] Component index

Returns:

Non-negative FDT offset of the component on success
Negative error code on error

int nfb_comp_find_in_parent(const struct nfb_device *dev, const char *compatible, unsigned index, int parent_offset)

Return FDT offset of a specific component within specific parent component.

This function goes through FDT and finds N-th node with matching ‘compatible’ property, but search only nodes in specific parent.

Parameters:

dev – [in] NFB device handle
compatible – [in] Component ‘compatible’ string
index – [in] Component index
parent_offset – [in] FDT offset of the parent component

Returns:

Non-negative FDT offset of the component on success
Negative error code on error

Component functions

struct nfb_comp *nfb_comp_open(const struct nfb_device *dev, int fdt_offset)

Open component specified by offset.

Parameters:

dev – [in] NFB device handle
fdt_offset – [in] FDT offset of the component

Returns:

Component handle on success
NULL on error (errno is set)

void nfb_comp_close(struct nfb_comp *component)

Close component.

Call this function when your work with the component is finished. After it returns, the component handle must not be used again.

Parameters:: component – [in] Component handle

ssize_t nfb_comp_read(const struct nfb_comp *comp, void *buf, size_t nbyte, off_t offset)

Read data from specific offset in the component.

Note

See man 2 pread on Linux

Parameters:

comp – [in] Component handle
buf – [in] Buffer to store the data to
nbyte – [in] Number of bytes to read
offset – [in] Offset in the component

Returns:

The amount of bytes successfully read on success
Negative error code on error (errno is set)

ssize_t nfb_comp_write(const struct nfb_comp *comp, const void *buf, size_t nbyte, off_t offset)

Write data to a specific offset in the component.

Parameters:

comp – [in] Component handle
buf – [in] Buffer containing the data to be written
nbyte – [in] Number of bytes to write
offset – [in] Offset in the component

Returns:

The amount of bytes successfully written on success
Negative error code on error (errno is set)

uint32_t nfb_comp_read32(struct nfb_comp *comp, off_t offset)

Read a 32 bit value from component.

Parameters:

comp – component
offset – offset inside component to read from

Return type:

Readen 32 bit value

Warning

It will not be able to find out, if the operation fails (e.g. when the offset is outside address space). For such cases use nfb_comp_read()

Note

There are similar nfb_comp_readN functions for 8, 16 and 64 bit read access.

void nfb_comp_write32(struct nfb_comp *comp, off_t offset, uint32_t val)

Write a 32 bit value to component.

Parameters:

comp – component
offset – offset inside component to read from
val – 32 bit value to write

Warning

It will not be able to find out, if the operation fails (e.g. when the offset is outside address space). For such cases use nfb_comp_write()

Note

There are similar nfb_comp_writeN functions for 8, 16 and 64 bit write access.

int nfb_comp_lock(const struct nfb_comp *component, uint32_t features)

Lock a component feature, prevent access in other process.

When a feature of the component is locked, no other lock() to the same feature of the component shall succeed before the feature of the component is unlocked again. To make this work across all processes, locking is done by the driver.

Simply put, this works as a simple mutex.

The expected usage is:

if (nfb_comp_lock(component, MY_F_DELETE | MY_F_ADD)) {
  // safe to assume no-one else has locked one of these component features
  ...
  nfb_comp_unlock(component, MY_F_DELETE | MY_F_ADD);
}

Parameters:

component – [in] Component handle
features – [in] Bitmask of user-defined features to lock

Returns:

1 on successful lock
0 on unsuccessful lock

void nfb_comp_unlock(const struct nfb_comp *component, uint32_t features)

Unlock a component feature.