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