diff options
author | Amar Takhar <amar@rtems.org> | 2016-01-17 00:47:50 -0500 |
---|---|---|
committer | Amar Takhar <verm@darkbeer.org> | 2016-05-02 20:51:23 -0400 |
commit | b35050917272ab536c8f4158e5c002f98a092796 (patch) | |
tree | 386dc0be827a10ff668e6d0b2b1ff52a1f49e9ed /bsp_howto/non_volatile_memory.rst | |
parent | Fix warnings. (diff) | |
download | rtems-docs-b35050917272ab536c8f4158e5c002f98a092796.tar.bz2 |
Split document into seperate files by section.
Diffstat (limited to '')
-rw-r--r-- | bsp_howto/non_volatile_memory.rst | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/bsp_howto/non_volatile_memory.rst b/bsp_howto/non_volatile_memory.rst new file mode 100644 index 0000000..b85f6ae --- /dev/null +++ b/bsp_howto/non_volatile_memory.rst @@ -0,0 +1,232 @@ +Non-Volatile Memory Driver +########################## + +The Non-Volatile driver is responsible for providing an +interface to various types of non-volatile memory. These +types of memory include, but are not limited to, Flash, EEPROM, +and battery backed RAM. The capabilities provided +by this class of device driver are: + +- Initialize the Non-Volatile Memory Driver + +- Optional Disable Read and Write Handlers + +- Open a Particular Memory Partition + +- Close a Particular Memory Partition + +- Read from a Particular Memory Partition + +- Write to a Particular Memory Partition + +- Erase the Non-Volatile Memory Area + +There is currently only one non-volatile device driver included in the +RTEMS source tree. The information provided in this chapter +is based on drivers developed for applications using RTEMS. +It is hoped that this driver model information can form the +basis for a standard non-volatile memory driver model that +can be supported in future RTEMS distribution. + +Major and Minor Numbers +======================= + +The *major* number of a device driver is its index in the +RTEMS Device Address Table. + +A *minor* number is associated with each device instance +managed by a particular device driver. An RTEMS minor number +is an ``unsigned32`` entity. Convention calls +dividing the bits in the minor number down into categories +that specify an area of non-volatile memory and a partition +with that area. This results in categories +like the following: + +- *area* - indicates a block of non-volatile memory + +- *partition* - indicates a particular address range with an area + +From the above, it should be clear that a single device driver +can support multiple types of non-volatile memory in a single system. +The minor number is used to distinguish the types of memory and +blocks of memory used for different purposes. + +Non-Volatile Memory Driver Configuration +======================================== + +There is not a standard non-volatile driver configuration table but some +fields are common across different drivers. The non-volatile memory driver +configuration table is typically an array of structures with each +structure containing the information for a particular area of +non-volatile memory. +The following is a list of the type of information normally required +to configure each area of non-volatile memory. + +*memory_type* + is the type of memory device in this area. Choices are battery backed RAM, + EEPROM, Flash, or an optional user-supplied type. If the user-supplied type + is configured, then the user is responsible for providing a set of + routines to program the memory. + +*memory* + is the base address of this memory area. + +*attributes* + is a pointer to a memory type specific attribute block. Some of + the fields commonly contained in this memory type specific attribute + structure area: + + *use_protection_algorithm* + + is set to TRUE to indicate that the protection (i.e. locking) algorithm + should be used for this area of non-volatile memory. A particular + type of non-volatile memory may not have a protection algorithm. + + *access* + + is an enumerated type to indicate the organization of the memory + devices in this memory area. The following is a list of the + access types supported by the current driver implementation: + - simple unsigned8 + - simple unsigned16 + - simple unsigned32 + - simple unsigned64 + - single unsigned8 at offset 0 in an unsigned16 + - single unsigned8 at offset 1 in an unsigned16 + - single unsigned8 at offset 0 in an unsigned32 + - single unsigned8 at offset 1 in an unsigned32 + - single unsigned8 at offset 2 in an unsigned32 + - single unsigned8 at offset 3 in an unsigned32 + + *depth* + + is the depth of the progamming FIFO on this particular chip. Some + chips, particularly EEPROMs, have the same programming algorithm but + vary in the depth of the amount of data that can be programmed in a single + block. + +*number_of_partitions* + is the number of logical partitions within this area. + +*Partitions* + is the address of the table that contains an entry to describe each + partition in this area. Fields within each element of this + table are defined as follows: + + *offset* + + is the offset of this partition from the base address of this area. + + *length* + + is the length of this partition. + +By dividing an area of memory into multiple partitions, it is possible +to easily divide the non-volatile memory for different purposes. + +Initialize the Non-Volatile Memory Driver +========================================= + +At system initialization, the non-volatile memory driver’s +initialization entry point will be invoked. As part of +initialization, the driver will perform +whatever initializatin is required on each non-volatile memory area. + +The discrete I/O driver may register device names for memory +partitions of particular interest to the system. Normally this +will be restricted to the device "/dev/nv_memory" to indicate +the entire device driver. + +Disable Read and Write Handlers +=============================== + +Depending on the target’s non-volatile memory configuration, it may be +possible to write to a status register and make the memory area completely +inaccessible. This is target dependent and beyond the standard capabilities +of any memory type. The user has the optional capability to provide +handlers to disable and enable access to a partiticular memory area. + +Open a Particular Memory Partition +================================== + +This is the driver open call. Usually this call does nothing other than +validate the minor number. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is often the place +to do this operation. + +Close a Particular Memory Partition +=================================== + +This is the driver close call. Usually this call does nothing. + +With some drivers, it may be necessary to allocate memory when a particular +device is opened. If that is the case, then this is the place +where that memory should be deallocated. + +Read from a Particular Memory Partition +======================================= + +This corresponds to the driver read call. After validating the minor +number and arguments, this call enables reads from the specified +memory area by invoking the user supplied "enable reads handler" +and then reads the indicated memory area. When +invoked the ``argument_block`` is actually a pointer to the following +structure type: +.. code:: c + + typedef struct { + uint32_t offset; + void \*buffer; + uint32_t length; + uint32_t status; + } Non_volatile_memory_Driver_arguments; + +The driver reads ``length`` bytes starting at ``offset`` into +the partition and places them at ``buffer``. The result is returned +in ``status``. + +After the read operation is complete, the user supplied "disable reads handler" +is invoked to protect the memory area again. + +Write to a Particular Memory Partition +====================================== + +This corresponds to the driver write call. After validating the minor +number and arguments, this call enables writes to the specified +memory area by invoking the "enable writes handler", then unprotecting +the memory area, and finally actually writing to the indicated memory +area. When invoked the ``argument_block`` is actually a pointer to +the following structure type: +.. code:: c + + typedef struct { + uint32_t offset; + void \*buffer; + uint32_t length; + uint32_t status; + } Non_volatile_memory_Driver_arguments; + +The driver writes ``length`` bytes from ``buffer`` and +writes them to the non-volatile memory starting at ``offset`` into +the partition. The result is returned in ``status``. + +After the write operation is complete, the "disable writes handler" +is invoked to protect the memory area again. + +Erase the Non-Volatile Memory Area +================================== + +This is one of the IOCTL functions supported by the I/O control +device driver entry point. When this IOCTL function is invoked, +the specified area of non-volatile memory is erased. + +.. COMMENT: Written by Eric Norum + +.. COMMENT: COPYRIGHT (c) 1988-2002. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + |