MTD device class sysfs ABI | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Class and device nodes

sysfs-class-mtd:1-43

MTD instance와 read-only variant를 /dev/mtdX character device 및 even·odd minor 번호에 연결합니다.

Geometry, flags, and identity

sysfs-class-mtd:45-107

Erase region, OOB·전체 size, flag bit, /proc/mtd 이름과 ASCII device type을 제공합니다.

Write and ECC geometry

sysfs-class-mtd:109-186

Media별 writesize, ECC strength·step과 -EUCLEAN을 결정하는 bitflip_threshold 의미를 설명합니다.

ECC and bad block counters

sysfs-class-mtd:188-224

ECC failure·corrected bit와 bad·BBT reserved block counter를 구분합니다.

Partition offset and OOB

sysfs-class-mtd:226-242

Partition을 식별하는 parent-relative byte offset과 client-available out-of-band byte를 제공합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 What: /sys/class/mtd/

2 Date: April 2009

3 KernelVersion: 2.6.29

4 Contact: [email protected]

5 Description:

6 The mtd/ class subdirectory belongs to the MTD subsystem

7 (MTD core).

9 What: /sys/class/mtd/mtdX/

10 Date: April 2009

11 KernelVersion: 2.6.29

12 Contact: [email protected]

13 Description:

14 The /sys/class/mtd/mtd{0,1,2,3,...} directories correspond

15 to each /dev/mtdX character device. These may represent

16 physical/simulated flash devices, partitions on a flash

17 device, or concatenated flash devices.

19 What: /sys/class/mtd/mtdXro/

20 Date: April 2009

21 KernelVersion: 2.6.29

22 Contact: [email protected]

23 Description:

24 These directories provide the corresponding read-only device

25 nodes for /sys/class/mtd/mtdX/ .

27 What: /sys/class/mtd/mtdX/dev

28 Date: April 2009

29 KernelVersion: 2.6.29

30 Contact: [email protected]

31 Description:

32 Major and minor numbers of the character device corresponding

33 to this MTD device (in <major>:<minor> format). This is the

34 read-write device so <minor> will be even.

36 What: /sys/class/mtd/mtdXro/dev

37 Date: April 2009

38 KernelVersion: 2.6.29

39 Contact: [email protected]

40 Description:

41 Major and minor numbers of the character device corresponding

42 to the read-only variant of the MTD device (in

43 <major>:<minor> format). In this case <minor> will be odd.

45 What: /sys/class/mtd/mtdX/erasesize

46 Date: April 2009

47 KernelVersion: 2.6.29

48 Contact: [email protected]

49 Description:

50 "Major" erase size for the device. If numeraseregions is

51 zero, this is the eraseblock size for the entire device.

52 Otherwise, the MEMGETREGIONCOUNT/MEMGETREGIONINFO ioctls

53 can be used to determine the actual eraseblock layout.

55 What: /sys/class/mtd/mtdX/flags

56 Date: April 2009

57 KernelVersion: 2.6.29

58 Contact: [email protected]

59 Description:

60 A hexadecimal value representing the device flags, ORed

61 together:

63 0x0400: MTD_WRITEABLE - device is writable

64 0x0800: MTD_BIT_WRITEABLE - single bits can be flipped

65 0x1000: MTD_NO_ERASE - no erase necessary

66 0x2000: MTD_POWERUP_LOCK - always locked after reset

68 What: /sys/class/mtd/mtdX/name

69 Date: April 2009

70 KernelVersion: 2.6.29

71 Contact: [email protected]

72 Description:

73 A human-readable ASCII name for the device or partition.

74 This will match the name in /proc/mtd .

76 What: /sys/class/mtd/mtdX/numeraseregions

77 Date: April 2009

78 KernelVersion: 2.6.29

79 Contact: [email protected]

80 Description:

81 For devices that have variable eraseblock sizes, this

82 provides the total number of erase regions. Otherwise,

83 it will read back as zero.

85 What: /sys/class/mtd/mtdX/oobsize

86 Date: April 2009

87 KernelVersion: 2.6.29

88 Contact: [email protected]

89 Description:

90 Number of OOB bytes per page.

92 What: /sys/class/mtd/mtdX/size

93 Date: April 2009

94 KernelVersion: 2.6.29

95 Contact: [email protected]

96 Description:

97 Total size of the device/partition, in bytes.

99 What: /sys/class/mtd/mtdX/type

100 Date: April 2009

101 KernelVersion: 2.6.29

102 Contact: [email protected]

103 Description:

104 One of the following ASCII strings, representing the device

105 type:

106

107 absent, ram, rom, nor, nand, mlc-nand, dataflash, ubi, unknown

108

109 What: /sys/class/mtd/mtdX/writesize

110 Date: April 2009

111 KernelVersion: 2.6.29

112 Contact: [email protected]

113 Description:

114 Minimal writable flash unit size. This will always be

115 a positive integer.

116

117 In the case of NOR flash it is 1 (even though individual

118 bits can be cleared).

119

120 In the case of NAND flash it is one NAND page (or a

121 half page, or a quarter page).

122

123 In the case of ECC NOR, it is the ECC block size.

124

125 What: /sys/class/mtd/mtdX/ecc_strength

126 Date: April 2012

127 KernelVersion: 3.4

128 Contact: [email protected]

129 Description:

130 Maximum number of bit errors that the device is capable of

131 correcting within each region covering an ECC step (see

132 ecc_step_size). This will always be a non-negative integer.

133

134 In the case of devices lacking any ECC capability, it is 0.

135

136 What: /sys/class/mtd/mtdX/bitflip_threshold

137 Date: April 2012

138 KernelVersion: 3.4

139 Contact: [email protected]

140 Description:

141 This allows the user to examine and adjust the criteria by which

142 mtd returns -EUCLEAN from mtd_read() and mtd_read_oob(). If the

143 maximum number of bit errors that were corrected on any single

144 region comprising an ecc step (as reported by the driver) equals

145 or exceeds this value, -EUCLEAN is returned. Otherwise, absent

146 an error, 0 is returned. Higher layers (e.g., UBI) use this

147 return code as an indication that an erase block may be

148 degrading and should be scrutinized as a candidate for being

149 marked as bad.

150

151 The initial value may be specified by the flash device driver.

152 If not, then the default value is ecc_strength.

153

154 The introduction of this feature brings a subtle change to the

155 meaning of the -EUCLEAN return code. Previously, it was

156 interpreted to mean simply "one or more bit errors were

157 corrected". Its new interpretation can be phrased as "a

158 dangerously high number of bit errors were corrected on one or

159 more regions comprising an ecc step". The precise definition of

160 "dangerously high" can be adjusted by the user with

161 bitflip_threshold. Users are discouraged from doing this,

162 however, unless they know what they are doing and have intimate

163 knowledge of the properties of their device. Broadly speaking,

164 bitflip_threshold should be low enough to detect genuine erase

165 block degradation, but high enough to avoid the consequences of

166 a persistent return value of -EUCLEAN on devices where sticky

167 bitflips occur. Note that if bitflip_threshold exceeds

168 ecc_strength, -EUCLEAN is never returned by the read operations.

169 Conversely, if bitflip_threshold is zero, -EUCLEAN is always

170 returned, absent a hard error.

171

172 This is generally applicable only to NAND flash devices with ECC

173 capability. It is ignored on devices lacking ECC capability;

174 i.e., devices for which ecc_strength is zero.

175

176 What: /sys/class/mtd/mtdX/ecc_step_size

177 Date: May 2013

178 KernelVersion: 3.10

179 Contact: [email protected]

180 Description:

181 The size of a single region covered by ECC, known as the ECC

182 step. Devices may have several equally sized ECC steps within

183 each writesize region.

184

185 It will always be a non-negative integer. In the case of

186 devices lacking any ECC capability, it is 0.

187

188 What: /sys/class/mtd/mtdX/ecc_failures

189 Date: June 2014

190 KernelVersion: 3.17

191 Contact: [email protected]

192 Description:

193 The number of failures reported by this device's ECC. Typically,

194 these failures are associated with failed read operations.

195

196 It will always be a non-negative integer. In the case of

197 devices lacking any ECC capability, it is 0.

198

199 What: /sys/class/mtd/mtdX/corrected_bits

200 Date: June 2014

201 KernelVersion: 3.17

202 Contact: [email protected]

203 Description:

204 The number of bits that have been corrected by means of the

205 device's ECC.

206

207 It will always be a non-negative integer. In the case of

208 devices lacking any ECC capability, it is 0.

209

210 What: /sys/class/mtd/mtdX/bad_blocks

211 Date: June 2014

212 KernelVersion: 3.17

213 Contact: [email protected]

214 Description:

215 The number of blocks marked as bad, if any, in this partition.

216

217 What: /sys/class/mtd/mtdX/bbt_blocks

218 Date: June 2014

219 KernelVersion: 3.17

220 Contact: [email protected]

221 Description:

222 The number of blocks that are marked as reserved, if any, in

223 this partition. These are typically used to store the in-flash

224 bad block table (BBT).

225

226 What: /sys/class/mtd/mtdX/offset

227 Date: March 2015

228 KernelVersion: 4.1

229 Contact: [email protected]

230 Description:

231 For a partition, the offset of that partition from the start

232 of the parent (another partition or a flash device) in bytes.

233 This attribute is absent on flash devices, so it can be used

234 to distinguish them from partitions.

235

236 What: /sys/class/mtd/mtdX/oobavail

237 Date: April 2018

238 KernelVersion: 4.16

239 Contact: [email protected]

240 Description:

241 Number of bytes available for a client to place data into

242 the out of band area.

243

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

MTD subsystem class

1-7

항목	한국어 전문 번역
What	/sys/class/mtd/
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	mtd/ class 하위 directory는 MTD subsystem(MTD core)에 속합니다.

MTD device instance

9-17

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	/sys/class/mtd/mtd{0,1,2,3,...} directory는 각 /dev/mtdX character device에 대응합니다. Physical 또는 simulated flash device, flash device의 partition, concatenated flash device를 나타낼 수 있습니다.

MTD sysfs hierarchy

/sys/class/mtd/mtdX/ per /dev/mtdX character devicemtdXro/ read-only device node variant

MTD class instance와 character device, read-only variant의 대응입니다.

Read-only MTD device

19-25

항목	한국어 전문 번역
What	/sys/class/mtd/mtdXro/
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	/sys/class/mtd/mtdX/에 대응하는 read-only device node를 제공합니다.

Read-write device number

27-34

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/dev
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	이 MTD device에 대응하는 character device의 major와 minor 번호를 <major>:<minor> 형식으로 제공합니다. Read-write device이므로 <minor>는 짝수입니다.

Read-only device number

36-43

항목	한국어 전문 번역
What	/sys/class/mtd/mtdXro/dev
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	MTD device의 read-only variant에 대응하는 character device의 major와 minor 번호를 <major>:<minor> 형식으로 제공합니다. 이 경우 <minor>는 홀수입니다.

MTD character device number

경로Variantminor

mtdX/devRead-write짝수

mtdXro/devRead-only홀수

Read-write와 read-only device node의 minor parity를 구분합니다.

Major erase size

45-53

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/erasesize
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Device의 major erase size입니다. numeraseregions가 0이면 전체 device의 eraseblock size입니다. 그렇지 않으면 MEMGETREGIONCOUNT와 MEMGETREGIONINFO ioctl로 실제 eraseblock layout을 확인할 수 있습니다.

MTD device flags

55-66

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/flags
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Device flag를 bitwise OR한 hexadecimal 값을 제공합니다. 정의된 flag는 MTD_WRITEABLE, MTD_BIT_WRITEABLE, MTD_NO_ERASE, MTD_POWERUP_LOCK입니다.

MTD flag bit

값Symbol의미

0x0400MTD_WRITEABLEDevice writable

0x0800MTD_BIT_WRITEABLESingle bit flip 가능

0x1000MTD_NO_ERASEErase 불필요

0x2000MTD_POWERUP_LOCKReset 뒤 항상 locked

원문에 나열된 hexadecimal flag와 의미입니다.

MTD device name

68-74

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/name
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Device 또는 partition의 사람이 읽을 수 있는 ASCII 이름입니다. /proc/mtd의 이름과 일치합니다.

Erase region count

76-83

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/numeraseregions
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Eraseblock size가 가변인 device에서는 전체 erase region 수를 제공합니다. 그렇지 않으면 0을 읽습니다.

OOB bytes per page

85-90

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/oobsize
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Page마다 존재하는 OOB byte 수입니다.

Device or partition size

92-97

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/size
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Device 또는 partition의 전체 크기를 byte 단위로 제공합니다.

MTD geometry attributes

속성값

erasesizeMajor erase size

numeraseregionsVariable erase region 수 또는 0

sizeDevice·partition 전체 byte 수

Erase geometry와 전체 byte 크기를 제공하는 기본 속성입니다.

MTD device type

99-107

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/type
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Device type을 나타내는 ASCII 문자열 하나를 제공합니다. 가능한 값은 absent, ram, rom, nor, nand, mlc-nand, dataflash, ubi, unknown입니다.

MTD type value

Type

absent

ram

rom

nor

nand

mlc-nand

dataflash

ubi

unknown

원문에 열거된 ASCII device type을 그대로 보존합니다.

Minimal writable unit

109-123

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/writesize
Date	2009년 4월
KernelVersion	2.6.29
Contact	[email protected]
Description	Flash의 minimum writable unit size이며 항상 양의 integer입니다.

Flash 종류별 writesize

Flash 종류writesize

NOR1, individual bit를 clear할 수 있어도 동일

NANDNAND page 하나 또는 half page·quarter page

ECC NORECC block size

원문의 media별 writesize 설명을 구조화했습니다.

ECC correction strength

125-134

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/ecc_strength
Date	2012년 4월
KernelVersion	3.4
Contact	[email protected]
Description	ECC step 하나가 덮는 각 region 안에서 device가 교정할 수 있는 bit error의 maximum 개수입니다. ecc_step_size도 참조하십시오. 항상 음이 아닌 integer입니다.

ECC capability가 없는 device에서는 0입니다.

ECC bitflip warning threshold

136-174

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/bitflip_threshold
Date	2012년 4월
KernelVersion	3.4
Contact	[email protected]
Description	mtd_read()와 mtd_read_oob()가 -EUCLEAN을 반환하는 기준을 user가 확인하고 조정할 수 있게 합니다. ECC step을 구성하는 단일 region 중 하나에서 교정된 bit error의 maximum 개수가 driver 보고 기준으로 이 값 이상이면 -EUCLEAN을 반환합니다. 그렇지 않고 error가 없으면 0을 반환합니다. UBI 같은 higher layer는 이 return code를 erase block이 저하되고 있으며 bad block 후보로 면밀히 조사해야 한다는 신호로 사용합니다.

초기값은 flash device driver가 지정할 수 있습니다. 지정하지 않으면 기본값은 ecc_strength입니다.

이 기능 도입으로 -EUCLEAN return code의 의미가 미묘하게 바뀌었습니다. 이전에는 단순히 하나 이상의 bit error가 교정되었다는 뜻이었지만, 이제는 ECC step을 구성하는 하나 이상의 region에서 위험할 정도로 많은 bit error가 교정되었다는 뜻입니다. User는 bitflip_threshold로 위험 기준을 정밀하게 조정할 수 있지만 device 특성을 깊이 이해하지 못한다면 권장하지 않습니다. 일반적으로 실제 erase block 저하를 감지할 만큼 낮으면서 sticky bitflip이 생기는 device에서 -EUCLEAN이 지속적으로 반환되는 결과를 피할 만큼 높아야 합니다. bitflip_threshold가 ecc_strength보다 크면 read operation은 -EUCLEAN을 반환하지 않습니다. 반대로 bitflip_threshold가 0이면 hard error가 없는 한 항상 -EUCLEAN을 반환합니다.

일반적으로 ECC capability가 있는 NAND flash device에만 적용됩니다. ecc_strength가 0인 ECC capability가 없는 device에서는 무시합니다.

-EUCLEAN threshold decision

ECC step의 각 region에서 교정된 bit error 보고단일 region의 maximum corrected bit 수 계산maximum >= bitflip_threshold이면 -EUCLEAN그 외 hard error가 없으면 0

ECC step의 region별 교정 bit 수를 threshold와 비교하는 read 결과입니다.

bitflip_threshold 경계값

조건Read 결과

bitflip_threshold = 0Hard error가 없으면 항상 -EUCLEAN

0 < threshold <= ecc_strengthMaximum corrected bit 수가 threshold 이상이면 -EUCLEAN

bitflip_threshold > ecc_strength-EUCLEAN을 반환하지 않음

ecc_strength = 0ECC capability 없음, threshold 무시

Threshold와 ecc_strength 관계가 -EUCLEAN 반환에 미치는 영향입니다.

ECC step size

176-186

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/ecc_step_size
Date	2013년 5월
KernelVersion	3.10
Contact	[email protected]
Description	ECC가 덮는 단일 region의 크기이며 ECC step이라고 합니다. Device는 writesize region마다 크기가 같은 ECC step을 여러 개 가질 수 있습니다.

항상 음이 아닌 integer입니다. ECC capability가 없는 device에서는 0입니다.

ECC failure count

188-197

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/ecc_failures
Date	2014년 6월
KernelVersion	3.17
Contact	[email protected]
Description	이 device의 ECC가 보고한 failure 수입니다. 보통 failed read operation과 관련됩니다.

항상 음이 아닌 integer입니다. ECC capability가 없는 device에서는 0입니다.

ECC corrected bit count

199-208

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/corrected_bits
Date	2014년 6월
KernelVersion	3.17
Contact	[email protected]
Description	Device의 ECC로 교정된 bit 수입니다.

항상 음이 아닌 integer입니다. ECC capability가 없는 device에서는 0입니다.

Bad block count

210-215

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/bad_blocks
Date	2014년 6월
KernelVersion	3.17
Contact	[email protected]
Description	이 partition에서 bad로 표시된 block이 있다면 그 개수를 제공합니다.

Reserved BBT block count

217-224

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/bbt_blocks
Date	2014년 6월
KernelVersion	3.17
Contact	[email protected]
Description	이 partition에서 reserved로 표시된 block이 있다면 그 개수를 제공합니다. 보통 in-flash bad block table(BBT)을 저장하는 데 사용합니다.

MTD health counter

속성Counter

ecc_failuresECC가 보고한 failure 수

corrected_bitsECC로 교정된 bit 수

bad_blocksBad로 표시된 block 수

bbt_blocksIn-flash BBT용 reserved block 수

ECC와 bad block 관련 누적·현재 counter를 구분합니다.

Partition offset

226-234

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/offset
Date	2015년 3월
KernelVersion	4.1
Contact	[email protected]
Description	Partition에서 parent 시작점으로부터 해당 partition의 offset을 byte 단위로 제공합니다. Parent는 다른 partition 또는 flash device일 수 있습니다. Flash device에는 이 속성이 없으므로 partition과 구분하는 데 사용할 수 있습니다.

offset 속성 존재 여부

대상offset

PartitionParent 시작점 기준 byte offset 존재

Flash device속성 없음

속성 유무로 partition과 flash device를 구분할 수 있습니다.

Client-available OOB bytes

236-242

항목	한국어 전문 번역
What	/sys/class/mtd/mtdX/oobavail
Date	2018년 4월
KernelVersion	4.16
Contact	[email protected]
Description	Client가 out-of-band area에 data를 넣을 수 있도록 사용할 수 있는 byte 수입니다.

MTD OOB byte attributes

속성Byte 수

oobsizePage당 전체 OOB byte

oobavailClient data에 사용 가능한 out-of-band byte

전체 page OOB와 client가 사용할 수 있는 부분을 구분합니다.