diff options
Diffstat (limited to 'bsp_howto/non_volatile_memory.rst')
| -rw-r--r-- | bsp_howto/non_volatile_memory.rst | 249 |
1 files changed, 116 insertions, 133 deletions
diff --git a/bsp_howto/non_volatile_memory.rst b/bsp_howto/non_volatile_memory.rst index 9ca7ddb..7187dbf 100644 --- a/bsp_howto/non_volatile_memory.rst +++ b/bsp_howto/non_volatile_memory.rst @@ -1,12 +1,16 @@ .. comment SPDX-License-Identifier: CC-BY-SA-4.0 +.. COMMENT: Written by Eric Norum +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + 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 +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 @@ -23,130 +27,119 @@ by this class of device driver are: - 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. +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. +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: +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 +- ``area`` - indicates a block of non-volatile memory -- *partition* - indicates a particular address range with an area +- ``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. +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. +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* +``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 + 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* +``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* +``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* + 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* - + 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. + vary in the depth of the amount of data that can be programmed in a + single block. -*number_of_partitions* +``number_of_partitions`` is the number of logical partitions within this area. -*Partitions* +``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* + 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* - + ``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. +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 +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. +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. +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 ================================== @@ -155,8 +148,8 @@ 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. +device is opened. If that is the case, then this is often the place to do this +operation. Close a Particular Memory Partition =================================== @@ -164,30 +157,29 @@ 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. +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 +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-block:: c typedef struct { - uint32_t offset; - void \*buffer; - uint32_t length; - uint32_t status; - } Non_volatile_memory_Driver_arguments; + 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``. +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. @@ -195,40 +187,31 @@ 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 +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-block:: c typedef struct { - uint32_t offset; - void \*buffer; - uint32_t length; - uint32_t status; - } Non_volatile_memory_Driver_arguments; + 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``. +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. +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. - +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. |