NeXTSTEPDRIVERKIT:Chapter4 5

Debugging a Driver

드라이버 디버깅(Debugging a Driver)

You have two choices for creating debugging messages: the IOLog() function and the Driver Debugging Module(DDM). Most drivers just use IOLog() until a need arises for the more powerful and complex DDM functions.
디버깅 메시지 작성을 하려 할때는 IOLog() 함수와 Driver Debugging Module(DDM) 의 두 가지 선택 사항이 있습니다. 대부분의 드라이버는 더 강력하고 복잡한 DDM 기능이 필요할 때까지는 IOLog() 를 사용합니다.

Another debugging tool, gdb, is described in NEXTSTEP Development Tools and Techniques. You can run the driver with gdb from Project Builder--the example located in /NextLibrary/Documentation/NextDev/Examples/DriverKit/TestDriver shows how to do this. NEXTSTEP Development Tools and Techniques also describes Project Builder.
또 다른 디버깅 도구로 NEXTSTEP Development Tools and Techniques 에 나와있는 gdb 가 있습니다. Project Builder 에서 gdb 와 같이 드라이버를 실행할 수 있습니다 - /NextLibrary/Documentation/NextDev/Examples/DriverKit/TestDriver 에 있는 예제에서는 이를 수행하는 방법을 보여줍니다. NEXTSTEP Development Tools and Techniques 에 Project Builder 에 대해 나와 있습니다.

IOLog 함수 사용하기(Using the IOLog Function)

Using IOLog() is similar to using printf() to print error or debug messages. You can output strings and parameters, just as for printf(). One difference is that output is placed in the /usr/adm/messages file instead of the console window. Place a call to IOLog() anywhere in your driver where you want to get information about the driver state--or to indicate that the driver reached that point during execution.
IOLog() 사용은 printf() 를 사용해서 오류 또는 디버그 메시지를 출력하는 것과 비슷합니다. printf() 와 마찬가지로 문자열과 매개 변수를 출력할 수 있습니다. 한 가지 차이점은 출력이 콘솔창 대신 /usr/adm/messages 파일에 위치한디는 것입니다. (디버깅을 위해서)드라이버 상태에 대한 정보를 얻거나 드라이버가 실행 중에 해당 위치에 도달했음을 나타내는 IOLog() 에 대한 호출을 드라이버에 배치하십시오.

IOLog() is useful both for status messages and as a basic debugging tool. Although IOLog() is useful for debugging, it can affect the timing of the driver. When timing is important, you should use DDM instead.
IOLog() 는 상태 메시지(status messages) 및 기본 디버깅 도구로 유용합니다. 하지만 IOLog() 는 디버깅에 유용하지만, 드라이버의 타이밍에 영향을 줄 수도 있습니다. 타이밍이 중요한 경우라면 DDM 을 사용해야 합니다.

See "Functions" in Chapter 5, "Driver Kit Reference", for more information about IOLog().
IOLog() 에 대한 자세한 내용은 5 장,"Driver Kit Reference" 의 "Functions" 를 참조하십시오.

Driver Debugging Module(DDM) 사용하기

The Driver Debugging Module (DDM) provides support for viewing debugging information without disturbing the timing of the kernel. By using the DDMViewer application (in /NextDeveloper/Demos), you can specify which information should be stored in the event buffer and display debugging information from this buffer.
DDM (Driver Debugging Module)은 커널의 타이밍을 방해하지 않고 디버깅 정보를 볼 수 있도록 지원합니다. DDMViewer 애플리케이션(/NextDeveloper/Demos 에 포함된)을 사용하여 이벤트 버퍼에 저장할 정보를 저장하고, 이 버퍼에서 디버깅 정보를 표시할 수 있습니다.

The core of DDM is a circular event buffer that stores the debugging information sent to it by drivers. Each entry in the buffer is timestamped (to the microsecond) and consists of a printf-style format string and up to five arguments associated with the format string. A call to the function that timestamps and stores one entry takes about 10 microseconds.
DDM 의 핵심은 드라이버가 보낸 디버깅 정보를 저장하는 순환 이벤트 버퍼(circular event buffer)입니다. 버퍼 내의 각 엔트리는 타임스탬프(마이크로 초)화되어, printf 스타일의 형식(format) 캐릭터 라인과 형식 캐릭터 라인에 관련된 최대 5 개의 인수로 구성됩니다. 하나의 항목을 타임 스탬프하고 저장하는 함수 호출은 약 10 마이크로초가 걸립니다.

DDM 이벤트 수집(Gathering DDM Events)

The function IOAddDDMEntry() adds an event to the DDM buffer. An event consists of a character string and several integer values. The IODEBUG() macro is provided to call IOAddDDMEntry(): A driver typically doesn't call IOAddDDMEntry() directly. Instead, the driver should define its own macros using the IODEBUG() macro, as in this example:
IOAddDDMEntry() 함수는 DDM 버퍼에 이벤트를 추가합니다. 이벤트는 문자열과 여러 정수 값(several integer values)으로 구성됩니다. IOAddDDMEntry() 를 호출하기 위해 IODEBUG() 매크로가 제공되는데, 일반적으로 드라이버는 'IOAddDDMEntry() 를 직접 호출하지는 않습니다. 그 대신에 드라이버는 이 예제에처럼 IODEBUG() 매크로를 사용해서 자체 매크로를 정의해야 합니다.

#define ddm_exp(x, a, b, c, d, e)      \
    IODEBUG(A7770_DDM_INDEX, DDM_EXPORTED, x, a, b, c, d, e)
#define ddm_him(x, a, b, c, d, e)      \
    IODEBUG(A7770_DDM_INDEX, DDM_HIM, x, a, b, c, d, e)

These macros can then be called like this:
그런 다음 이 매크로를 호출할 수 있습니다:

ddm_him("abort_channel chan %d\n", channel, 2,3,4,5);

ddm_him("scb_int_preempt: scb 0x%x index %d haStat %s\n",
    scb_ptr, scb_index,
    IOFindNameForValue(compstat, scbHaStatValues),
    4,5);

A word of mask bits controls the collection of DDM entries. All calls to IODEBUG() don't add data to DDM's circular buffer--only those events whose mask bits are enabled are added. The mask bits are enabled and disabled by a user-level tool like DDMViewer. A driver isn't (and shouldn't be) concerned about which mask bits are enabled. Typically you turn on one or two bits of the mask word to study the trace information for a particular module.
마스크 비트 워드(word of mask bits)는 DDM 항목의 콜렉션을 제어합니다. IODEBUG() 에 대한 모든 호출은 DDM 순환 버퍼에 데이터를 추가하지 않으며 마스크 비트가 활성화 된 이벤트 만 추가됩니다. DDMViewer 와 같은 사용자 수준 도구로 마스크 비트를 사용하거나 사용하지 않도록 설정할 수 있습니다. 드라이버는 어떤 마스크 비트가 활성화되는지에 대해 영향을 받지 않아야 합니다. 일반적으로 특정 모듈(particular module)에 대한 추적 정보(trace information)를 연구하기 위해 마스크 워드의 1-2 비트를 켭니다.

See the SCSI example driver in /NextDeveloper/Examples/DriverKit/Adaptec1542B, which illustrates all aspects of using DDM.
DDM 사용의 모든 측면을 살펴보려면 /NextDeveloper/Examples/DriverKit/Adaptec1542B 의 SCSI 예제 드라이버를 참조하십시오.

DDMViewer 로 DDM 이벤트보기

You can examine DDM traces at the user-level with the DDMViewer application, which is located in /NextDeveloper/Demos. You can also specify DDM mask bits with this application. DDMViewer can be run on any computer running NEXTSTEP, not just the machine being tested.
/NextDeveloper/Demos 에 있는 DDMViewer 응용 프로그램을 사용하면 사용자 수준에서 DDM 추적(traces)을 조사(examine)할 수 있습니다. 이 응용 프로그램(DDMViewer)에서 DDM 마스크 비트를 지정할 수도 있습니다. DDMViewer 는 테스트중인 시스템뿐만 아니라 NEXTSTEP 을 실행하는 모든 컴퓨터에서 실행할 수 있습니다.

The DDMViewer window contains the following controls:
DDMViewer 창에는 다음과 같은 컨트롤들이 있습니다:

• Device Name field. Enter the name of the target to which you want to attach. The name is determined by the driver.
  Device Name field. 첨부하려는 대상의 이름을 입력하십시오. 이름은 드라이버에 의해 결정됩니다.
• Host Name field. Enter the name of the host on which the target is running. Leave it empty if you are debugging a driver or kernel on the current machine.
  Host Name field. 대상(target)이 실행되고 있는 호스트의 이름을 입력하십시오. 현재 컴퓨터에서 드라이버 나 커널을 디버깅하는 경우에는 비워 두십시오.
• List button. Click this button to start and stop the display of DDM entries. Entries are displayed starting from the last event in time and scrolling backward.
  List button. DDM 항목의 표시를 시작하고 중지하려면 이 단추를 누르십시오. 항목은 마지막 이벤트부터 시작되며 뒤로 스크롤해서 표시됩니다.
• Set Mask button. Click this button to send the mask defined in the Mask window (see below) to the target.
  Set Mask button. Mask window (아래 참조)에 정의된 마스크를 대상(target)으로 보내려면 이 버튼을 클릭하십시오.
• Disable button. Click this button to freeze the state of the DDM buffer at the target. Click again to reenable.
  Disable button. 대상에서 DDM 버퍼의 상태를 고정하려면 이 단추를 누르십시오. 다시 클릭하면 다시 활성화됩니다.
• Clear Window button. Click this button to clear the display area.
  Clear Window button. 표시 영역을 지우려면 이 버튼을 클릭하십시오.
• Clear Buffer button. Click this button to clear the target's circular DDM buffer.
  Clear Buffer button. 대상의 원형 DDM 버퍼(circular DDM buffer)를 지우려면 이 단추를 클릭하십시오.

You can specify the value of the DDM mask bits by name if you open a .ddm file that specifies the names of the mask bits. You create .ddm files with an editor such as Edit. Here's an example of a .ddm file:
마스크 비트의 이름을 지정하는 .ddm 파일을 열면 DDM 마스크 비트 값을 이름으로 지정할 수 있습니다. Edit 같은 편집기를 사용해서 .ddm 파일을 작성합니다. 다음은 .ddm 파일의 예입니다:

#
#  DDMViewer data file for kernel devices.
#
Index : 0 : "Kernel Devices"
#
#  Common fields.
#
0x0001 : "Device Object"
0x0002 : "Disk Object"
0x0004 : "Net"
0x0020 : "DMA"
#
#  SCSI.
#
0x0100 : "SCSI Control"
0x0400 : "SCSI Disk"

Comments start with "#". The line that starts with "Index" defines which DDM Mask word is being defined (there are currently four mask words). The Index line also defines the name of the window associated with this set of mask bits. All other lines define one bit in the mask word, specifying the value of the bit and an ASCII name equivalent. The SCSI example driver in /NextDeveloper/Examples/DriverKit/Adaptec1542B has a sample .ddm file.
주석은 "#" 으로 시작합니다. "Index"로 시작하는 줄은 정의된 DDM 마스크 단어(DDM Mask word)를 정의합니다(현재는 4 개의 마스크 단어가 존재). Index 행은 이 마스크 비트 세트와 연관된 창의 이름도 정의합니다. 다른 모든 행은 비트의 값과 동등한 ASCII 이름을 지정하여 마스크 단어에서 하나의 비트를 정의합니다. /NextDeveloper/Examples/DriverKit/Adaptec1542B 의 SCSI 예제 드라이버에는 샘플 .ddm 파일이 있습니다.