1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: Written by Eric Norum |
---|
4 | .. COMMENT: COPYRIGHT (c) 1988-2002. |
---|
5 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
6 | .. COMMENT: All rights reserved. |
---|
7 | |
---|
8 | Non-Volatile Memory Driver |
---|
9 | ########################## |
---|
10 | |
---|
11 | The Non-Volatile driver is responsible for providing an interface to various |
---|
12 | types of non-volatile memory. These types of memory include, but are not |
---|
13 | limited to, Flash, EEPROM, and battery backed RAM. The capabilities provided |
---|
14 | by this class of device driver are: |
---|
15 | |
---|
16 | - Initialize the Non-Volatile Memory Driver |
---|
17 | |
---|
18 | - Optional Disable Read and Write Handlers |
---|
19 | |
---|
20 | - Open a Particular Memory Partition |
---|
21 | |
---|
22 | - Close a Particular Memory Partition |
---|
23 | |
---|
24 | - Read from a Particular Memory Partition |
---|
25 | |
---|
26 | - Write to a Particular Memory Partition |
---|
27 | |
---|
28 | - Erase the Non-Volatile Memory Area |
---|
29 | |
---|
30 | There is currently only one non-volatile device driver included in the RTEMS |
---|
31 | source tree. The information provided in this chapter is based on drivers |
---|
32 | developed for applications using RTEMS. It is hoped that this driver model |
---|
33 | information can form the basis for a standard non-volatile memory driver model |
---|
34 | that can be supported in future RTEMS distribution. |
---|
35 | |
---|
36 | Major and Minor Numbers |
---|
37 | ======================= |
---|
38 | |
---|
39 | The ``major`` number of a device driver is its index in the RTEMS Device |
---|
40 | Address Table. |
---|
41 | |
---|
42 | A ``minor`` number is associated with each device instance managed by a |
---|
43 | particular device driver. An RTEMS minor number is an ``unsigned32`` entity. |
---|
44 | Convention calls dividing the bits in the minor number down into categories |
---|
45 | that specify an area of non-volatile memory and a partition with that area. |
---|
46 | This results in categories like the following: |
---|
47 | |
---|
48 | - ``area`` - indicates a block of non-volatile memory |
---|
49 | |
---|
50 | - ``partition`` - indicates a particular address range with an area |
---|
51 | |
---|
52 | From the above, it should be clear that a single device driver can support |
---|
53 | multiple types of non-volatile memory in a single system. The minor number is |
---|
54 | used to distinguish the types of memory and blocks of memory used for different |
---|
55 | purposes. |
---|
56 | |
---|
57 | Non-Volatile Memory Driver Configuration |
---|
58 | ======================================== |
---|
59 | |
---|
60 | There is not a standard non-volatile driver configuration table but some fields |
---|
61 | are common across different drivers. The non-volatile memory driver |
---|
62 | configuration table is typically an array of structures with each structure |
---|
63 | containing the information for a particular area of non-volatile memory. The |
---|
64 | following is a list of the type of information normally required to configure |
---|
65 | each area of non-volatile memory. |
---|
66 | |
---|
67 | ``memory_type`` |
---|
68 | is the type of memory device in this area. Choices are battery backed RAM, |
---|
69 | EEPROM, Flash, or an optional user-supplied type. If the user-supplied |
---|
70 | type is configured, then the user is responsible for providing a set of |
---|
71 | routines to program the memory. |
---|
72 | |
---|
73 | ``memory`` |
---|
74 | is the base address of this memory area. |
---|
75 | |
---|
76 | ``attributes`` |
---|
77 | is a pointer to a memory type specific attribute block. Some of the fields |
---|
78 | commonly contained in this memory type specific attribute structure area: |
---|
79 | |
---|
80 | ``use_protection_algorithm`` |
---|
81 | is set to TRUE to indicate that the protection (i.e. locking) algorithm |
---|
82 | should be used for this area of non-volatile memory. A particular type |
---|
83 | of non-volatile memory may not have a protection algorithm. |
---|
84 | |
---|
85 | ``access`` |
---|
86 | is an enumerated type to indicate the organization of the memory |
---|
87 | devices in this memory area. The following is a list of the access |
---|
88 | types supported by the current driver implementation: |
---|
89 | |
---|
90 | - simple unsigned8 |
---|
91 | - simple unsigned16 |
---|
92 | - simple unsigned32 |
---|
93 | - simple unsigned64 |
---|
94 | - single unsigned8 at offset 0 in an unsigned16 |
---|
95 | - single unsigned8 at offset 1 in an unsigned16 |
---|
96 | - single unsigned8 at offset 0 in an unsigned32 |
---|
97 | - single unsigned8 at offset 1 in an unsigned32 |
---|
98 | - single unsigned8 at offset 2 in an unsigned32 |
---|
99 | - single unsigned8 at offset 3 in an unsigned32 |
---|
100 | |
---|
101 | ``depth`` |
---|
102 | is the depth of the progamming FIFO on this particular chip. Some |
---|
103 | chips, particularly EEPROMs, have the same programming algorithm but |
---|
104 | vary in the depth of the amount of data that can be programmed in a |
---|
105 | single block. |
---|
106 | |
---|
107 | ``number_of_partitions`` |
---|
108 | is the number of logical partitions within this area. |
---|
109 | |
---|
110 | ``Partitions`` |
---|
111 | is the address of the table that contains an entry to describe each |
---|
112 | partition in this area. Fields within each element of this table are |
---|
113 | defined as follows: |
---|
114 | |
---|
115 | ``offset`` |
---|
116 | is the offset of this partition from the base address of this area. |
---|
117 | |
---|
118 | ``length`` |
---|
119 | is the length of this partition. |
---|
120 | |
---|
121 | By dividing an area of memory into multiple partitions, it is possible to |
---|
122 | easily divide the non-volatile memory for different purposes. |
---|
123 | |
---|
124 | Initialize the Non-Volatile Memory Driver |
---|
125 | ========================================= |
---|
126 | |
---|
127 | At system initialization, the non-volatile memory driver's initialization entry |
---|
128 | point will be invoked. As part of initialization, the driver will perform |
---|
129 | whatever initializatin is required on each non-volatile memory area. |
---|
130 | |
---|
131 | The discrete I/O driver may register device names for memory partitions of |
---|
132 | particular interest to the system. Normally this will be restricted to the |
---|
133 | device "/dev/nv_memory" to indicate the entire device driver. |
---|
134 | |
---|
135 | Disable Read and Write Handlers |
---|
136 | =============================== |
---|
137 | |
---|
138 | Depending on the target's non-volatile memory configuration, it may be possible |
---|
139 | to write to a status register and make the memory area completely inaccessible. |
---|
140 | This is target dependent and beyond the standard capabilities of any memory |
---|
141 | type. The user has the optional capability to provide handlers to disable and |
---|
142 | enable access to a partiticular memory area. |
---|
143 | |
---|
144 | Open a Particular Memory Partition |
---|
145 | ================================== |
---|
146 | |
---|
147 | This is the driver open call. Usually this call does nothing other than |
---|
148 | validate the minor number. |
---|
149 | |
---|
150 | With some drivers, it may be necessary to allocate memory when a particular |
---|
151 | device is opened. If that is the case, then this is often the place to do this |
---|
152 | operation. |
---|
153 | |
---|
154 | Close a Particular Memory Partition |
---|
155 | =================================== |
---|
156 | |
---|
157 | This is the driver close call. Usually this call does nothing. |
---|
158 | |
---|
159 | With some drivers, it may be necessary to allocate memory when a particular |
---|
160 | device is opened. If that is the case, then this is the place where that |
---|
161 | memory should be deallocated. |
---|
162 | |
---|
163 | Read from a Particular Memory Partition |
---|
164 | ======================================= |
---|
165 | |
---|
166 | This corresponds to the driver read call. After validating the minor number |
---|
167 | and arguments, this call enables reads from the specified memory area by |
---|
168 | invoking the user supplied "enable reads handler" and then reads the indicated |
---|
169 | memory area. When invoked the ``argument_block`` is actually a pointer to the |
---|
170 | following structure type: |
---|
171 | |
---|
172 | .. code-block:: c |
---|
173 | |
---|
174 | typedef struct { |
---|
175 | uint32_t offset; |
---|
176 | void *buffer; |
---|
177 | uint32_t length; |
---|
178 | uint32_t status; |
---|
179 | } Non_volatile_memory_Driver_arguments; |
---|
180 | |
---|
181 | The driver reads ``length`` bytes starting at ``offset`` into the partition and |
---|
182 | places them at ``buffer``. The result is returned in ``status``. |
---|
183 | |
---|
184 | After the read operation is complete, the user supplied "disable reads handler" |
---|
185 | is invoked to protect the memory area again. |
---|
186 | |
---|
187 | Write to a Particular Memory Partition |
---|
188 | ====================================== |
---|
189 | |
---|
190 | This corresponds to the driver write call. After validating the minor number |
---|
191 | and arguments, this call enables writes to the specified memory area by |
---|
192 | invoking the "enable writes handler", then unprotecting the memory area, and |
---|
193 | finally actually writing to the indicated memory area. When invoked the |
---|
194 | ``argument_block`` is actually a pointer to the following structure type: |
---|
195 | |
---|
196 | .. code-block:: c |
---|
197 | |
---|
198 | typedef struct { |
---|
199 | uint32_t offset; |
---|
200 | void *buffer; |
---|
201 | uint32_t length; |
---|
202 | uint32_t status; |
---|
203 | } Non_volatile_memory_Driver_arguments; |
---|
204 | |
---|
205 | The driver writes ``length`` bytes from ``buffer`` and writes them to the |
---|
206 | non-volatile memory starting at ``offset`` into the partition. The result is |
---|
207 | returned in ``status``. |
---|
208 | |
---|
209 | After the write operation is complete, the "disable writes handler" is invoked |
---|
210 | to protect the memory area again. |
---|
211 | |
---|
212 | Erase the Non-Volatile Memory Area |
---|
213 | ================================== |
---|
214 | |
---|
215 | This is one of the IOCTL functions supported by the I/O control device driver |
---|
216 | entry point. When this IOCTL function is invoked, the specified area of |
---|
217 | non-volatile memory is erased. |
---|