요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Status and messages
writecache.rst:77-11414개 status counter와 flush, cleaner, linear target 전환을 이용한 안전한 cache 제거 순서를 다룹니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=================
Writecache target
=================
The writecache target caches writes on persistent memory or on SSD. It
doesn't cache reads because reads are supposed to be cached in page cache
in normal RAM.
When the device is constructed, the first sector should be zeroed or the
first sector should contain valid superblock from previous invocation.
Constructor parameters:
1. type of the cache device - "p" or "s"
- p - persistent memory
- s - SSD
2. the underlying device that will be cached
3. the cache device
4. block size (4096 is recommended; the maximum block size is the page
size)
5. the number of optional parameters (the parameters with an argument
count as two)
start_sector n (default: 0)
offset from the start of cache device in 512-byte sectors
high_watermark n (default: 50)
start writeback when the number of used blocks reach this
watermark
low_watermark x (default: 45)
stop writeback when the number of used blocks drops below
this watermark
writeback_jobs n (default: unlimited)
limit the number of blocks that are in flight during
writeback. Setting this value reduces writeback
throughput, but it may improve latency of read requests
autocommit_blocks n (default: 64 for pmem, 65536 for ssd)
when the application writes this amount of blocks without
issuing the FLUSH request, the blocks are automatically
committed
autocommit_time ms (default: 1000)
autocommit time in milliseconds. The data is automatically
committed if this time passes and no FLUSH request is
received
fua (by default on)
applicable only to persistent memory - use the FUA flag
when writing data from persistent memory back to the
underlying device
nofua
applicable only to persistent memory - don't use the FUA
flag when writing back data and send the FLUSH request
afterwards
- some underlying devices perform better with fua, some
with nofua. The user should test it
cleaner
when this option is activated (either in the constructor
arguments or by a message), the cache will not promote
new writes (however, writes to already cached blocks are
promoted, to avoid data corruption due to misordered
writes) and it will gradually writeback any cached
data. The userspace can then monitor the cleaning
process with "dmsetup status". When the number of cached
blocks drops to zero, userspace can unload the
dm-writecache target and replace it with dm-linear or
other targets.
max_age n
specifies the maximum age of a block in milliseconds. If
a block is stored in the cache for too long, it will be
written to the underlying device and cleaned up.
metadata_only
only metadata is promoted to the cache. This option
improves performance for heavier REQ_META workloads.
pause_writeback n (default: 3000)
pause writeback if there was some write I/O redirected to
the origin volume in the last n milliseconds
Status:
1. error indicator - 0 if there was no error, otherwise error number
2. the number of blocks
3. the number of free blocks
4. the number of blocks under writeback
5. the number of read blocks
6. the number of read blocks that hit the cache
7. the number of write blocks
8. the number of write blocks that hit uncommitted block
9. the number of write blocks that hit committed block
10. the number of write blocks that bypass the cache
11. the number of write blocks that are allocated in the cache
12. the number of write requests that are blocked on the freelist
13. the number of flush requests
14. the number of discarded blocks
Messages:
flush
Flush the cache device. The message returns successfully
if the cache device was flushed without an error
flush_on_suspend
Flush the cache device on next suspend. Use this message
when you are going to remove the cache device. The proper
sequence for removing the cache device is:
1. send the "flush_on_suspend" message
2. load an inactive table with a linear target that maps
to the underlying device
3. suspend the device
4. ask for status and verify that there are no errors
5. resume the device, so that it will use the linear
target
6. the cache device is now inactive and it can be deleted
cleaner
See above "cleaner" constructor documentation.
clear_stats
Clear the statistics that are reported on the status line
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Persistent write cache의 역할
1-11`writecache` target은 persistent memory 또는 SSD에 write를 cache합니다. Read는 일반 RAM의 page cache에 저장된다고 가정하므로 cache하지 않습니다.
Device를 구성할 때 cache device의 첫 sector는 zero이거나 이전 invocation에서 만든 valid superblock을 포함해야 합니다.
Write만 persistent cache를 거치고 read caching은 normal RAM page cache에 맡깁니다.
Constructor parameter
12-23첫 parameter는 cache device type이며 `p`는 persistent memory, `s`는 SSD입니다. 이어 cache할 underlying device, cache device, block size를 지정합니다. Block size는 4096을 권장하며 최대값은 page size입니다.
마지막으로 optional parameter 수를 지정합니다. Argument를 갖는 parameter는 parameter name과 argument를 각각 세므로 두 개로 계산합니다.
Cache medium, origin, cache device, block geometry와 optional argument count를 순서대로 지정합니다.
Watermark, commit과 cleaner option
24-76`start_sector n`은 cache device 시작에서 512-byte sector 단위 offset이며 기본값은 0입니다. `high_watermark n`은 used block 수가 이 watermark에 도달하면 writeback을 시작하며 기본값은 50입니다. `low_watermark x`는 used block 수가 이 값 아래로 내려가면 writeback을 멈추며 기본값은 45입니다.
`writeback_jobs n`은 writeback 중 in-flight block 수를 제한하며 기본값은 unlimited입니다. 값을 설정하면 writeback throughput은 줄지만 read request latency가 개선될 수 있습니다.
`autocommit_blocks n`은 application이 FLUSH request 없이 지정 block 수를 쓰면 자동 commit합니다. 기본값은 pmem에서 64, SSD에서 65536입니다. `autocommit_time ms`는 FLUSH가 오지 않은 채 지정 시간이 지나면 자동 commit하는 millisecond 값이며 기본값은 1000입니다.
`fua`는 기본적으로 켜져 있고 persistent memory에만 적용됩니다. Persistent memory에서 underlying device로 data를 writeback할 때 FUA flag를 사용합니다. `nofua`도 persistent memory 전용이며 writeback에 FUA를 사용하지 않고 이후 FLUSH request를 보냅니다. Underlying device에 따라 `fua` 또는 `nofua` 성능이 더 좋을 수 있으므로 사용자가 시험해야 합니다.
`cleaner`를 constructor argument 또는 message로 활성화하면 cache는 새 write를 promote하지 않고 cached data를 점진적으로 writeback합니다. 다만 이미 cached된 block에 대한 write는 write ordering이 뒤바뀌어 data corruption이 생기지 않도록 계속 promote합니다.
Userspace는 `dmsetup status`로 cleaning을 monitor할 수 있습니다. Cached block 수가 0이 되면 dm-writecache target을 unload하고 dm-linear 또는 다른 target으로 교체할 수 있습니다.
`max_age n`은 block의 최대 cache age를 millisecond로 지정합니다. Cache에 너무 오래 머문 block은 underlying device에 기록하고 정리합니다. `metadata_only`는 metadata만 cache로 promote하며 REQ_META 비중이 높은 workload의 성능을 개선합니다.
`pause_writeback n`의 기본값은 3000입니다. 최근 n millisecond 안에 origin volume으로 redirect된 write I/O가 있으면 writeback을 일시 중지합니다.
Watermark와 시간·block 수 기준으로 writeback 및 durability를 조정합니다.
Medium 특성, draining, age와 workload type에 따라 정책을 선택합니다.
Cache를 안전하게 비운 뒤 다른 target으로 교체할 수 있는 상태를 만듭니다.
Status line의 14개 counter
77-93Status는 순서대로 다음 14개 값을 반환합니다: error가 없으면 0이고 아니면 error number인 indicator, 전체 block 수, free block 수, writeback 중인 block 수, read block 수, cache hit한 read block 수, write block 수, uncommitted block을 hit한 write block 수, committed block을 hit한 write block 수, cache를 bypass한 write block 수, cache에 할당된 write block 수, freelist 때문에 block된 write request 수, flush request 수, discarded block 수입니다.
Status line의 position을 그대로 보존한 counter 목록입니다.
Flush와 cache 제거 message
94-114`flush`는 cache device를 flush합니다. Error 없이 flush되면 message가 성공을 반환합니다.
`flush_on_suspend`는 다음 suspend 때 cache device를 flush합니다. Cache device를 제거할 예정일 때 사용합니다.
정상 제거 순서는 다음과 같습니다. 1) `flush_on_suspend` message를 보냅니다. 2) Underlying device를 mapping하는 linear target의 inactive table을 load합니다. 3) Device를 suspend합니다. 4) Status를 요청해 error가 없음을 확인합니다. 5) Device를 resume하여 linear target을 사용하게 합니다. 6) 이제 cache device가 inactive이므로 삭제할 수 있습니다.
`cleaner` message는 앞서 설명한 cleaner constructor option을 활성화합니다. `clear_stats`는 status line에 보고되는 statistics를 지웁니다.
즉시 flush, 다음 suspend drain, cleaner 전환과 counter reset을 제공합니다.
Inactive linear table로 전환한 뒤에만 cache device를 삭제합니다.
Configuration
writecache.rst:1-76Write-only persistent cache의 medium, watermark, commit, FUA와 cleaner 정책을 구성합니다.