← Documents Documentation/admin-guide/device-mapper/kcopyd.rst GitHub 원문 ↗

Linux 6.18.37 · Administration / Device Mapper

kcopyd

한 block device의 sector 범위를 여러 destination으로 비동기 복사하는 Device Mapper 내부 API의 수명주기와 자료 구조를 설명합니다.

Source pathDocumentation/admin-guide/device-mapper/kcopyd.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

비동기 복사 모델

kcopyd.rst:1-27

Client가 예약한 memory page를 이용해 하나의 source와 여러 destination 영역을 구성합니다.

요청, callback과 정리

kcopyd.rst:28-47

`kcopyd_copy()`가 작업을 시작하고 callback으로 오류와 context를 반환한 뒤 client를 해제합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 ======
2 kcopyd
3 ======
4
5 Kcopyd provides the ability to copy a range of sectors from one block-device
6 to one or more other block-devices, with an asynchronous completion
7 notification. It is used by dm-snapshot and dm-mirror.
8
9 Users of kcopyd must first create a client and indicate how many memory pages
10 to set aside for their copy jobs. This is done with a call to
11 kcopyd_client_create()::
12
13 int kcopyd_client_create(unsigned int num_pages,
14 struct kcopyd_client **result);
15
16 To start a copy job, the user must set up io_region structures to describe
17 the source and destinations of the copy. Each io_region indicates a
18 block-device along with the starting sector and size of the region. The source
19 of the copy is given as one io_region structure, and the destinations of the
20 copy are given as an array of io_region structures::
21
22 struct io_region {
23 struct block_device *bdev;
24 sector_t sector;
25 sector_t count;
26 };
27
28 To start the copy, the user calls kcopyd_copy(), passing in the client
29 pointer, pointers to the source and destination io_regions, the name of a
30 completion callback routine, and a pointer to some context data for the copy::
31
32 int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
33 unsigned int num_dests, struct io_region *dests,
34 unsigned int flags, kcopyd_notify_fn fn, void *context);
35
36 typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
37 void *context);
38
39 When the copy completes, kcopyd will call the user's completion routine,
40 passing back the user's context pointer. It will also indicate if a read or
41 write error occurred during the copy.
42
43 When a user is done with all their copy jobs, they should call
44 kcopyd_client_destroy() to delete the kcopyd client, which will release the
45 associated memory pages::
46
47 void kcopyd_client_destroy(struct kcopyd_client *kc);
48

3. 한국어 전문 번역

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

Block device 사이의 비동기 sector 복사

1-7

`kcopyd`는 한 block device의 sector 범위를 하나 이상의 다른 block device로 복사하고, 작업이 끝나면 비동기 완료 알림을 제공합니다. `dm-snapshot`과 `dm-mirror`가 이 기능을 사용합니다.

kcopyd 복사 모델
Source block device의 sector 범위`kcopyd` 비동기 복사Destination block device 1..N완료 callback

하나의 source 영역을 여러 destination으로 복사한 뒤 callback으로 완료를 알립니다.

Client와 작업용 memory page 예약

8-15

`kcopyd` 사용자는 먼저 client를 만들고 복사 작업에 따로 확보할 memory page 수를 지정해야 합니다. `kcopyd_client_create()`의 `num_pages`가 예약량을 정하고, 생성된 client pointer는 `result`로 반환됩니다.

   int kcopyd_client_create(unsigned int num_pages,
                            struct kcopyd_client **result);

Source와 destination을 나타내는 io_region

16-27

복사 작업을 시작하려면 source와 destination을 설명하는 `io_region` 구조체를 준비합니다. 각 영역은 block device, 시작 sector, 영역 크기를 가리킵니다. Source는 `io_region` 하나로, destination은 `io_region` 배열로 전달합니다.

   struct io_region {
      struct block_device *bdev;
      sector_t sector;
      sector_t count;
   };
io_region 필드
필드형식의미
`bdev``struct block_device *`대상 block device
`sector``sector_t`영역의 시작 sector
`count``sector_t`영역의 sector 수

하나의 연속된 block-device 영역을 세 필드로 기술합니다.

복사 요청과 완료 callback

28-41

복사를 시작할 때 `kcopyd_copy()`에 client pointer, source와 destination `io_region` pointer, destination 수, flags, 완료 callback 이름, 복사별 context data pointer를 전달합니다.

   int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
                   unsigned int num_dests, struct io_region *dests,
                   unsigned int flags, kcopyd_notify_fn fn, void *context);

   typedef void (*kcopyd_notify_fn)(int read_err, unsigned int write_err,
				    void *context);

복사가 끝나면 `kcopyd`가 사용자의 완료 routine을 호출하고 처음 전달한 `context` pointer를 돌려줍니다. Callback의 `read_err`와 `write_err`는 작업 중 read 또는 write 오류가 발생했는지를 알립니다.

비동기 완료 경로
`kcopyd_copy()` 호출Source에서 readDestination 1..N에 write`kcopyd_notify_fn` 호출`read_err`, `write_err`, `context` 반환

호출자는 작업 context를 넘기고 callback에서 같은 context와 오류 상태를 받습니다.

Client 해제

42-47

모든 복사 작업을 마친 사용자는 `kcopyd_client_destroy()`를 호출해 `kcopyd` client를 삭제해야 합니다. 이 호출은 client와 연결된 memory page도 해제합니다.

   void kcopyd_client_destroy(struct kcopyd_client *kc);