NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO
#include <ddi/nvram/nvram.h>
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DDI
The NVRAM device driver provides a basic interface by abstracting the access methods to the underlying NVRAM hardware. Basically, the driver implements routines that allow the device driver client to read/write from/to the NVRAM space.
It is assumed that there is an intermediate layer (logical NVRAM driver) between an application and the device driver. Such a logical NVRAM driver would typically synchronize concurrent accesses to the NVRAM space. It would also protect some NVRAM areas against application accesses. Such protected NVRAM areas may be reserved for firmware usage or may map another device (e.g. a real-time-clock device).
The character string ``nvram'' names the timer device class. The driver client use the device class name to get the driver service routines from the device registry as described in svDeviceLookup(9DKI).
The NVRAM device driver is a mono-client driver. The driver registy prevents multiple look-ups to be done on the same NVRAM device driver instance. Typically, only a logical NVRAM driver interfaces directly to the NVRAM device driver. The logical NVRAM driver, in turn, provides an application interface (which might be multi-client oriented).
The NvramDevOps structure specifies the interface of the NVRAM device driver service routines.
typedef struct NvramDevOps { NvramVersion version; KnError (*open) (NvramId id); KnError (*read) (NvramId id, NvramSize offset, void* buffer, NvramSize size); KnError (*write) (NvramId id, NvramSize offset, void* buffer, NvramSize size); void (*close) (NvramId id); } NvramDevOps;
The version field specifies the highest version number of the NVRAM device driver interface supported by the driver. Currently, only one version is available and therefore the version field must be set to zero (NVRAM_VERSION_INITIAL). In the future, the NVRAM device driver interface may be extended, but backward compatibility is guaranteed; extra methods may be added to the NvramDevOps structure but the existing methods will remain unchanged.
The open routine must be the first call to the driver. The open routine makes the NVRAM device operational and enables subsequent invocations of the read, write and close routines. The id argument specifies a given NVRAM device. It is obtained from the device registry entry dev_id field. open returns K_OK on success. The K_EFAIL error code is returned if the driver is not able to put the device in an operation state.
The read routine (synchronously) reads data from the NVRAM device to a memory buffer. The id argument specifies a given NVRAM device and is obtained from the device registry entry dev_id field. The offset argument specifies the start offset in bytes from the beginning of the NVRAM space. The buffer argument specifies the start address of a memory buffer. The size argument specifies the number of bytes to read. Note that read does not check correctness of input arguments. For example, if offset is beyond the NVRAM space, the driver behavior is unpredictable. The read routine returns K_OK on success. The K_EFAIL error code is returned if the driver encounters an (hardware) error condition during the read.
The write routine (synchronously) writes data from a memory buffer to the NVRAM device. The id argument specifies a given NVRAM device. It is obtained from the device registry entry dev_id field. The offset argument specifies the start offset in bytes from the beginning of the NVRAM space. The buffer argument specifies the start address of a memory buffer. The size argument specifies the number of bytes to write. Note that write does not check correctness of input arguments. For example, if offset is beyond the NVRAM space, the driver behavior is unpredictable. The write routine returns K_OK on success. The K_EFAIL error code is returned if the driver encounters an (hardware) error condition during the write.
The close routine must be the last call to the driver because it makes the NVRAM device non-operational. Once the device is closed, the only routine allowed to call is open.The id argument specifies a given NVRAM device. It is obtained from the device registry entry dev_id field.
Properties attached to the NVRAM device node give the device driver client certain physical characteristics of the NVRAM device. The device driver client must take into account such characteristics in order to properly perform operations on the NVRAM device.
The nvram-layout property, NVRAM_PROP_LAYOUT, specifies the physical layout of the NVRAM device space. The property value is an array of NvramPropChunk values:
typedef struct NvramPropChunk { NvramSize size; uint32_f attr; } NvramPropChunk;
The size field specifies the chunk size in bytes. Note that the nvram-layout property array covers the entire NVRAM space. So, the start offset of a given chunk is calculated as the sum of the size fields of all previous chunks.
The attr field may take the following values:
A chunk should not be accessed by a driver client (for example, the chunk maps a RTC device)..
The contents of the chunk data, used by the hardware to boot the system (for example, the chunk is used by firmware).
The chunk is available for a driver client and that client may read/write from/to the chunk without restriction. In others words, this chunk is free to be managed.
Note that the NVRAM device driver does not check the access permissions when a read or write is issued. It is up to the driver client to respect the physical NVRAM layout specified by the 'nvram-layout' property.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | ATTRIBUTES | SEE ALSO