요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
========================
Linux Switchtec Support
========================
Microsemi's "Switchtec" line of PCI switch devices is already
supported by the kernel with standard PCI switch drivers. However, the
Switchtec device advertises a special management endpoint which
enables some additional functionality. This includes:
* Packet and Byte Counters
* Firmware Upgrades
* Event and Error logs
* Querying port link status
* Custom user firmware commands
The switchtec kernel module implements this functionality.
Interface
=========
The primary means of communicating with the Switchtec management firmware is
through the Memory-mapped Remote Procedure Call (MRPC) interface.
Commands are submitted to the interface with a 4-byte command
identifier and up to 1KB of command specific data. The firmware will
respond with a 4-byte return code and up to 1KB of command-specific
data. The interface only processes a single command at a time.
Userspace Interface
===================
The MRPC interface will be exposed to userspace through a simple char
device: /dev/switchtec#, one for each management endpoint in the system.
The char device has the following semantics:
* A write must consist of at least 4 bytes and no more than 1028 bytes.
The first 4 bytes will be interpreted as the Command ID and the
remainder will be used as the input data. A write will send the
command to the firmware to begin processing.
* Each write must be followed by exactly one read. Any double write will
produce an error and any read that doesn't follow a write will
produce an error.
* A read will block until the firmware completes the command and return
the 4-byte Command Return Value plus up to 1024 bytes of output
data. (The length will be specified by the size parameter of the read
call -- reading less than 4 bytes will produce an error.)
* The poll call will also be supported for userspace applications that
need to do other things while waiting for the command to complete.
The following IOCTLs are also supported by the device:
* SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number
of partitions in the device.
* SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for
any specified partition in flash.
* SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps
indicating all uncleared events.
* SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags
for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct
with the event_id, index and flags set (index being the partition or PFF
number for non-global events). It returns whether the event has
occurred, the number of times and any event specific data. The flags
can be used to clear the count or enable and disable actions to
happen when the event occurs.
By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag,
you can set an event to trigger a poll command to return with
POLLPRI. In this way, userspace can wait for events to occur.
* SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert
between PCI Function Framework number (used by the event system)
and Switchtec Logic Port ID and Partition number (which is more
user friendly).
Non-Transparent Bridge (NTB) Driver
===================================
An NTB hardware driver is provided for the Switchtec hardware in
ntb_hw_switchtec. Currently, it only supports switches configured with
exactly 2 NT partitions and zero or more non-NT partitions. It also requires
the following configuration settings:
* Both NT partitions must be able to access each other's GAS spaces.
Thus, the bits in the GAS Access Vector under Management Settings
must be set to support this.
* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
to be set)
NT EP BAR 2 will be dynamically configured as a Direct Window, and
the configuration file does not need to configure it explicitly.
Please refer to Documentation/driver-api/ntb.rst in Linux source tree for an overall
understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
Hardware Driver in this stack.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Linux Switchtec 지원
1-18Microsemi의 `Switchtec` PCI switch device 제품군은 표준 PCI switch driver를 통해 이미 kernel에서 지원합니다.
Switchtec device는 추가 기능을 제공하는 특별한 management endpoint도 알립니다. 여기에는 packet·byte counter, firmware upgrade, event·error log, port link status query, custom user firmware command가 포함됩니다.
`switchtec` kernel module이 이 management 기능을 구현합니다.
========================
Linux Switchtec Support
========================
Microsemi's "Switchtec" line of PCI switch devices is already
supported by the kernel with standard PCI switch drivers. However, the
Switchtec device advertises a special management endpoint which
enables some additional functionality. This includes:
* Packet and Byte Counters
* Firmware Upgrades
* Event and Error logs
* Querying port link status
* Custom user firmware commands
The switchtec kernel module implements this functionality.
MRPC management interface
19-29Switchtec management firmware와 통신하는 주된 수단은 memory-mapped Remote Procedure Call(MRPC) interface입니다.
Command는 4-byte command identifier와 최대 1KB의 command-specific input data로 제출합니다. Firmware response는 4-byte return code와 최대 1KB의 command-specific output data로 구성됩니다.
MRPC interface는 한 번에 command 하나만 처리합니다.
단일 command slot에서 request와 response를 순차 처리합니다.
Interface
=========
The primary means of communicating with the Switchtec management firmware is
through the Memory-mapped Remote Procedure Call (MRPC) interface.
Commands are submitted to the interface with a 4-byte command
identifier and up to 1KB of command specific data. The firmware will
respond with a 4-byte return code and up to 1KB of command-specific
data. The interface only processes a single command at a time.
Userspace character device와 ioctl
30-82MRPC interface는 system의 management endpoint마다 하나씩 생성되는 단순 character device `/dev/switchtec#`로 userspace에 노출됩니다.
`write`는 최소 4 byte, 최대 1028 byte여야 합니다. 처음 4 byte는 Command ID로 해석하고 나머지는 input data로 사용하며, write가 firmware에 command를 보내 처리를 시작합니다.
각 write 뒤에는 정확히 한 번의 read가 와야 합니다. Write를 연속 두 번 호출하거나 앞선 write 없이 read하면 오류가 발생합니다.
`read`는 firmware가 command를 완료할 때까지 block한 뒤 4-byte Command Return Value와 최대 1024-byte output data를 반환합니다. 반환 길이는 read call의 size parameter로 지정하며 4 byte보다 적게 읽으면 오류입니다.
Command 완료를 기다리는 동안 다른 일을 해야 하는 userspace application을 위해 `poll` call도 지원합니다.
`SWITCHTEC_IOCTL_FLASH_INFO`는 firmware 길이와 device의 partition 수를 가져옵니다. `SWITCHTEC_IOCTL_FLASH_PART_INFO`는 지정한 flash partition의 address와 length를 가져옵니다.
`SWITCHTEC_IOCTL_EVENT_SUMMARY`는 clear되지 않은 모든 event를 나타내는 bitmap 구조체를 읽습니다.
`SWITCHTEC_IOCTL_EVENT_CTL`은 event의 현재 count를 얻고 flag를 clear·설정합니다. 입력 `switchtec_ioctl_event_ctl` 구조체에는 `event_id`, `index`, `flags`를 지정하며, non-global event에서 index는 partition 또는 PFF 번호입니다.
이 ioctl은 event 발생 여부, 발생 횟수, event-specific data를 반환합니다. Flag로 count를 clear하거나 event 발생 시 수행할 action을 enable·disable할 수 있습니다.
`SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL`을 사용하면 event 발생 시 `poll`이 `POLLPRI`와 함께 반환되도록 설정할 수 있어 userspace가 event를 기다릴 수 있습니다.
`SWITCHTEC_IOCTL_PFF_TO_PORT`와 `SWITCHTEC_IOCTL_PORT_TO_PFF`는 event system이 쓰는 PCI Function Framework(PFF) 번호와, 사용자에게 더 익숙한 Switchtec Logic Port ID·Partition 번호 사이를 변환합니다.
Userspace Interface
===================
The MRPC interface will be exposed to userspace through a simple char
device: /dev/switchtec#, one for each management endpoint in the system.
The char device has the following semantics:
* A write must consist of at least 4 bytes and no more than 1028 bytes.
The first 4 bytes will be interpreted as the Command ID and the
remainder will be used as the input data. A write will send the
command to the firmware to begin processing.
* Each write must be followed by exactly one read. Any double write will
produce an error and any read that doesn't follow a write will
produce an error.
* A read will block until the firmware completes the command and return
the 4-byte Command Return Value plus up to 1024 bytes of output
data. (The length will be specified by the size parameter of the read
call -- reading less than 4 bytes will produce an error.)
* The poll call will also be supported for userspace applications that
need to do other things while waiting for the command to complete.
The following IOCTLs are also supported by the device:
* SWITCHTEC_IOCTL_FLASH_INFO - Retrieve firmware length and number
of partitions in the device.
* SWITCHTEC_IOCTL_FLASH_PART_INFO - Retrieve address and lengeth for
any specified partition in flash.
* SWITCHTEC_IOCTL_EVENT_SUMMARY - Read a structure of bitmaps
indicating all uncleared events.
* SWITCHTEC_IOCTL_EVENT_CTL - Get the current count, clear and set flags
for any event. This ioctl takes in a switchtec_ioctl_event_ctl struct
with the event_id, index and flags set (index being the partition or PFF
number for non-global events). It returns whether the event has
occurred, the number of times and any event specific data. The flags
can be used to clear the count or enable and disable actions to
happen when the event occurs.
By using the SWITCHTEC_IOCTL_EVENT_FLAG_EN_POLL flag,
you can set an event to trigger a poll command to return with
POLLPRI. In this way, userspace can wait for events to occur.
* SWITCHTEC_IOCTL_PFF_TO_PORT and SWITCHTEC_IOCTL_PORT_TO_PFF convert
between PCI Function Framework number (used by the event system)
and Switchtec Logic Port ID and Partition number (which is more
user friendly).
Non-Transparent Bridge driver
83-102Switchtec hardware용 NTB hardware driver는 `ntb_hw_switchtec`으로 제공됩니다.
현재는 정확히 2개의 NT partition과 0개 이상의 non-NT partition으로 구성된 switch만 지원합니다.
두 NT partition은 서로의 GAS space에 접근할 수 있어야 하므로 Management Settings의 GAS Access Vector bit를 이를 지원하도록 설정해야 합니다.
Kernel configuration은 반드시 NTB 지원을 포함해야 하며 `CONFIG_NTB`를 설정해야 합니다.
NT EP BAR 2는 Direct Window로 동적으로 구성되므로 configuration file에서 명시적으로 설정할 필요가 없습니다.
Linux NTB stack의 전체 구조는 `Documentation/driver-api/ntb.rst`를 참조합니다. `ntb_hw_switchtec`은 이 stack에서 NTB Hardware Driver로 동작합니다.
Non-Transparent Bridge (NTB) Driver
===================================
An NTB hardware driver is provided for the Switchtec hardware in
ntb_hw_switchtec. Currently, it only supports switches configured with
exactly 2 NT partitions and zero or more non-NT partitions. It also requires
the following configuration settings:
* Both NT partitions must be able to access each other's GAS spaces.
Thus, the bits in the GAS Access Vector under Management Settings
must be set to support this.
* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
to be set)
NT EP BAR 2 will be dynamically configured as a Direct Window, and
the configuration file does not need to configure it explicitly.
Please refer to Documentation/driver-api/ntb.rst in Linux source tree for an overall
understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
Hardware Driver in this stack.
요약과 해설
switchtec.rst:1-102Switchtec management endpoint는 단일-command MRPC를 `/dev/switchtec#`로 노출합니다. Userspace는 4-byte command ID를 포함한 write 뒤 정확히 한 번 read하고, ioctl로 flash·event·PFF mapping을 제어하며, 별도 `ntb_hw_switchtec` driver는 제한된 2-NT-partition 구성을 지원합니다.