53c700 드라이버 참고 사항

지원 chip과 endian 설정

이 드라이버는 53c700과 53c700-66 chip을 지원하며, 53c710은 53c700 emulation mode에서만 지원한다. 동기 전송은 -66과 710에서만 제공하고, disconnect와 tagged command queueing도 구현한 완전한 기능의 core driver다.

53c700은 시스템 bus에 직접 연결해야 하므로 card detector를 이 core driver 바깥의 wrapper로 작성한다. 구현 예는 `NCR_D700.[ch]`와 `lasi700.[ch]`이며, `53c700.[ch]`의 주석은 실제 board driver가 채워야 할 부분을 표시한다.

Big-endian 아키텍처에서 chip을 little-endian mode로 써야 한다면 compile-time symbol `CONFIG_53C700_LE_ON_BE`를 정의한다. 대표적으로 parisc의 700이 이 구성을 사용한다.

.. SPDX-License-Identifier: GPL-2.0

=======================
The 53c700 Driver Notes
=======================

General Description
===================

This driver supports the 53c700 and 53c700-66 chips.  It also supports
the 53c710 but only in 53c700 emulation mode.  It is full featured and
does sync (-66 and 710 only), disconnects and tag command queueing.

Since the 53c700 must be interfaced to a bus, you need to wrapper the
card detector around this driver.  For an example, see the
NCR_D700.[ch] or lasi700.[ch] files.

The comments in the 53c700.[ch] files tell you which parts you need to
fill in to get the driver working.


Compile Time Flags
==================

A compile time flag is::

        CONFIG_53C700_LE_ON_BE

define if the chipset must be supported in little endian mode on a big
endian architecture (used for the 700 on parisc).

Chip core 연결 정보와 clock

53c700 chip core를 실제 SCSI driver에 연결하려면 board 배선에 관한 세 정보가 필수다. SCSI core clock 속도, interrupt line, 53c700 register가 놓인 memory 또는 I/O space 주소다. Card BIOS에서 SCSI ID를 읽는 방법과 differential 배선 여부도 필요할 수 있다.

Interrupt와 register 위치는 일반 사양서나 다른 운영체제의 동작하는 driver 설정에서 찾을 수 있다. Clock은 기술 문서 깊숙이 숨어 있는 경우가 많지만 synchronous와 asynchronous divider를 설정하는 데 꼭 필요하다.

제조사는 보통 chip이 최적으로 동작하는 범위에서 가장 낮은 clock을 선택한다. 별도 clock chip 비용을 피하려고 CPU 또는 bus clock으로 구동하는 board도 있다. 권장 동작 clock은 53c700 25MHz, 53c700-66 50MHz, 53c710 40MHz다.

Using the Chip Core Driver
==========================

In order to plumb the 53c700 chip core driver into a working SCSI
driver, you need to know three things about the way the chip is wired
into your system (or expansion card).

1. The clock speed of the SCSI core
2. The interrupt line used
3. The memory (or io space) location of the 53c700 registers.

Optionally, you may also need to know other things, like how to read
the SCSI Id from the card bios or whether the chip is wired for
differential operation.

Usually you can find items 2. and 3. from general spec. documents or
even by examining the configuration of a working driver under another
operating system.

The clock speed is usually buried deep in the technical literature.
It is required because it is used to set up both the synchronous and
asynchronous dividers for the chip.  As a general rule of thumb,
manufacturers set the clock speed at the lowest possible setting
consistent with the best operation of the chip (although some choose
to drive it off the CPU or bus clock rather than going to the expense
of an extra clock chip).  The best operation clock speeds are:

=========  =====
53c700     25MHz
53c700-66  50MHz
53c710     40Mhz
=========  =====

Glue driver 생명주기와 interrupt

Glue layer는 최소한 detect와 release entry를 갖는 표준 SCSI driver로 작성한다. Detect에서는 `NCR_700_Host_Parameters` 크기의 영역을 할당하고 0으로 지워 모든 기본값을 만든 뒤 필요한 parameter를 채운다.

그 다음 `NCR_700_intr`을 interrupt line에 연결하고 host template과 parameter를 `NCR_700_detect()`에 넘긴다. 해당 `request_*_region()`도 호출하고 register base address를 host parameter의 `base` pointer에 저장한다.

Release에서는 할당한 `NCR_700_Host_Parameters`를 해제하고 짝이 되는 `release_*_region()`과 interrupt 해제를 수행한다.

일반적인 interrupt 등록은 `request_irq(irq, NCR_700_intr, <irq flags>, <driver name>, host)`이며 `host`는 `NCR_700_detect()`의 반환값이다. 여러 chip이 한 card에 있고 어느 chip 집합이 interrupt를 요구했는지 register로 구분할 수 있을 때만 custom handler에서 `NCR_700_intr()`을 직접 호출한다.

Writing Your Glue Driver
========================

This will be a standard SCSI driver (I don't know of a good document
describing this, just copy from some other driver) with at least a
detect and release entry.

In the detect routine, you need to allocate a struct
NCR_700_Host_Parameters sized memory area and clear it (so that the
default values for everything are 0).  Then you must fill in the
parameters that matter to you (see below), plumb the NCR_700_intr
routine into the interrupt line and call NCR_700_detect with the host
template and the new parameters as arguments.  You should also call
the relevant request_*_region function and place the register base
address into the 'base' pointer of the host parameters.

In the release routine, you must free the NCR_700_Host_Parameters that
you allocated, call the corresponding release_*_region and free the
interrupt.

Handling Interrupts
-------------------

In general, you should just plumb the card's interrupt line in with

request_irq(irq, NCR_700_intr, <irq flags>, <driver name>, host);

where host is the return from the relevant NCR_700_detect() routine.

You may also write your own interrupt handling routine which calls
NCR_700_intr() directly.  However, you should only really do this if
you have a card with more than one chip on it and you can read a
register to tell which set of chips wants the interrupt.

NCR_700_Host_Parameters 설정

`clock`은 chip MHz 값으로 반드시 설정한다. `base`도 필수이며 register set의 I/O 또는 memory 영역 base를 가리킨다. 64-bit architecture에서도 이 값은 32-bit 폭이므로 register를 memory의 낮은 32-bit 범위에 mapping해야 한다.

`pci_dev`는 PCI board device이며 non-PCI board에서는 `NULL`로 둔다. `pci_alloc_consistent()`와 `pci_map_*()`에 사용된다. 53c710 전용 `dmode_extra`는 DMODE register의 bus output pin을 제어하며 `DMODE_FC1`, `DMODE_FC2` 조합이다. Pin 의미는 board 설계자가 정하므로 대개 무시해도 된다.

Differential bus이면 `differential=1`, 53c710이면 `chip710=1`로 둔다. `CONFIG_53C700_LE_ON_BE`가 켜진 big-endian system에서 chip이 little-endian으로 동작하면 `force_le_on_be=1`을 쓴다. 53c710의 DMA 8-byte burst를 끄려면 `burst_disable`을 설정한다.

Settable NCR_700_Host_Parameters
--------------------------------

The following are a list of the user settable parameters:

clock: (MANDATORY)
  Set to the clock speed of the chip in MHz.

base: (MANDATORY)
  Set to the base of the io or mem region for the register set. On 64
  bit architectures this is only 32 bits wide, so the registers must be
  mapped into the low 32 bits of memory.

pci_dev: (OPTIONAL)
  Set to the PCI board device.  Leave NULL for a non-pci board.  This is
  used for the pci_alloc_consistent() and pci_map_*() functions.

dmode_extra: (OPTIONAL, 53c710 only)
  Extra flags for the DMODE register.  These are used to control bus
  output pins on the 710.  The settings should be a combination of
  DMODE_FC1 and DMODE_FC2.  What these pins actually do is entirely up
  to the board designer.  Usually it is safe to ignore this setting.

differential: (OPTIONAL)
  Set to 1 if the chip drives a differential bus.

force_le_on_be: (OPTIONAL, only if CONFIG_53C700_LE_ON_BE is set)
  Set to 1 if the chip is operating in little endian mode on a big
  endian architecture.

chip710: (OPTIONAL)
  Set to 1 if the chip is a 53c710.

burst_disable: (OPTIONAL, 53c710 only)
  Disable 8 byte bursting for DMA transfers.