Using catalogs: /etc/sgml/catalog Using stylesheet: /usr/share/sgml/docbook/utils-0.6.9/docbook-utils.dsl#html Working on: /home/jdavila/lucas/doc-manual-linux-controlador-mca/doc-manual-linux-controlador-mca.xml Interfaz de Programaci�n del Controlador MCA

Interfaz de Programaci�n del Controlador MCA

Alan Cox

David Weinehall

Chris Beauregard


Tabla de contenidos
1. Introducci�n
2. Bugs Conocidos Y Suposiciones
3. Funciones P�blicas Suministradas
mca_find_adapter --  busca adaptadores
mca_find_unused_adapter --  busca adaptadores sin usar
mca_read_stored_pos --  lee los registros POS de los datos de arranque
mca_read_pos --  lee el registro POS de la tarjeta
mca_write_pos --  lee el registro POS de la tarjeta
mca_set_adapter_name --  Establece la descripci�n de la tarjeta
mca_set_adapter_procfn --  Establece la retrollamada /proc
mca_is_adapter_used --  chequea si fue pedido por un controlador
mca_mark_as_used --  pide un dispositivo MCA
mca_mark_as_unused --  libera un dispositivo MCA
mca_get_adapter_name --  obtiene la descripci�n del adaptador
mca_isadapter --  chequea si el slot mantiene un adaptador
mca_isenabled --  chequa si el slot mantiene un adaptador
4. Funciones DMA Suministradas
mca_enable_dma --  canal en el que habilitar el DMA
mca_disable_dma --  canal en el que deshabilitar el DMA
mca_set_dma_addr --  carga una direcci�n DMA de 24 bits
mca_get_dma_addr --  carga una direcci�n DMA de 24 bits
mca_set_dma_count --  carga una cuenta de transferencia de 16 bits
mca_get_dma_residue --  obtiene los bytes que quedan por transferir
mca_set_dma_io --  establece el puerto para una transferencia de E/S
mca_set_dma_mode --  establece el modo de DMA
5. Sobre la Traducci�n

Cap�tulo 1. Introducci�n

Las funciones del bus MCA suministran una interfaz generalizada para encontrar tarjetas del bus MCA, pedirles un controlador, y para leer y manipular los registros POS sin ser conscientes de los entresijos de la placa madre o de cierta magia profunda espec�fica de los dispositivos de la placa.

La interfaz b�sica de los dispositivos del bus MCA es el slot. Cada slot est� numerado y los n�meros de slots virtuales son asignados a los dispositivos internos. Realmente el usar pci_dev como con otros buses no tiene sentido en los contextos MCA, ya que los recursos del bus MCA requieren una interpretaci�n espec�fica de la tarjeta.

Finalmente, las funciones del bus MCA suministran un conjunto paralelo de funciones DMA parecidas a las funciones DMA del bus ISA, tan cerradamente como es posible, aunque tambi�n soportan las funcionalidades adicionales DMA en las controladoras del bus MCA.


Cap�tulo 2. Bugs Conocidos Y Suposiciones

Ninguno.


Cap�tulo 3. Funciones P�blicas Suministradas

mca_find_adapter

Nombre

mca_find_adapter --  busca adaptadores

Argumentos

id

Identificaci�n del bus MCA en el que buscar

start

slot de comienzo

Descripci�n

Busca en la configuraci�n del MCA adaptadores que se correspondan con la identificaci�n de 16 bits. La primera vez deber�a de ser llamado para que empiece en cero, y entonces las llamadas posteriores que se har�n pasando el valor de retorno de la llamada previa hasta que sea retornado MCA_NOTFOUND.

Los adaptadores deshabilitados no son reportados.

mca_find_unused_adapter

Nombre

mca_find_unused_adapter --  busca adaptadores sin usar

Argumentos

id

Identificaci�n del bus MCA en el que buscar

start

slot de comienzo

Descripci�n

Busca en la configuraci�n del MCA adaptadores que se correspondan con la identificaci�n de 16 bits. La primera vez deber�a de ser llamado para que empiece en cero, y entonces las llamadas posteriores que se har�n pasando el valor de retorno de la llamada previa hasta que sea retornado MCA_NOTFOUND.

Los adaptadores que han sido reclamados por controladores o que est�n deshabilitados no son reportados. Esta funci�n permite a un controlador buscar tarjetas adicionales cuando quiz�s alguien ya las controle.

mca_read_stored_pos

Nombre

mca_read_stored_pos --  lee los registros POS de los datos de arranque

Argumentos

slot

n�mero de slot desde donde leer

reg

registro desde donde leer

Descripci�n

Obtiene un valor POS que fue almacenado en tiempo de arranque por el n�cleo cuando este busc� en el espacio del MCA. Es retornado el valor del registro. Registros perdidos o inv�lidos devuelven un 0.

mca_read_pos

Nombre

mca_read_pos --  lee el registro POS de la tarjeta

Argumentos

slot

n�mero de slot desde donde leer

reg

registro de donde leer

Descripci�n

Obtiene un valor POS directamente del hardware para obtener el valor actual. Esto es mucho m�s lento que mca_read_stored_pos y quiz�s no sea llamado desde el contexto de interrupciones. Maneja la magia profunda requerida para los dispositivos en la placa de forma transparente.

mca_write_pos

Nombre

mca_write_pos --  lee el registro POS de la tarjeta

Argumentos

slot

n�mero de slot desde donde leer

reg

registro de donde leer

byte

byte a escrigir en los registros POS

Descripci�n

Almacena un valor POS directamente al hardware. Normalmente no necesitar�as usar esta funci�n y deber�as de tener un muy buen conocimiento del bus MCA antes de hacerlo. Realizando esto de forma incorrecta puedes da�ar el hardware.

Esta funci�n quiz�s no sea usada desde un contexto de interrupciones.

Nota que esto es t�cnicamente Algo Malo, como dice el equipo t�cnico de IBM, s�lo deber�as de establecer valores POS a trav�s de sus utilidades. En todo caso, algunos dispositivos como el 3c523 recomiendan que les escribas algunos datos para asegurarte de que la configuraci�n es consistente. Yo dir�a que IBM est� en lo cierto, pero me gusta que mis controladores funcionen.

Esta funci�n no puede chequear para ver si m�ltiples dispositivos est�n con los mismos recursos, por lo tanto quiz�s veas humo m�gico si alguien se l�a.

mca_set_adapter_name

Nombre

mca_set_adapter_name --  Establece la descripci�n de la tarjeta

Argumentos

slot

slot a nombrar

name

cadena de texto para el nombre

Descripci�n

Esta funci�n establece el nombre reportado a trav�s de /proc para este slot adaptador. Esto es �nicamente para informaci�n de usuario. Estableciendo un nombre borra cualquier nombre previo.

mca_set_adapter_procfn

Nombre

mca_set_adapter_procfn --  Establece la retrollamada /proc

Argumentos

slot

slot a configurar

procfn

funci�n de retrollamada a llamar para /proc

dev

informaci�n del dispositivo pasada a la retrollamada

Descripci�n

Establece una retrollamada de informaci�n para /proc/mca/slot?. La funci�n es llamada con el buffer, slot y puntero al dispositivo (o alguna otra informaci�n igualmente informativa del contexto, o nada, si lo prefieres), y se espera que ponga informaci�n �til en el buffer. El nombre del adaptador, ID, y registros POS fueron imprimidos antes de esta llamada, por lo tanto no lo hagas otra vez.

Deber�a de ser llamada con un procfn NULL cuando un m�dulo se desregistra, entonces preveniendo que el n�cleo rompa y otras semejantes cosas feas.

mca_is_adapter_used

Nombre

mca_is_adapter_used --  chequea si fue pedido por un controlador

Argumentos

slot

slot a chequear

Descripci�n

Retorna 1 si el slot ha sido pedido por un controlador

mca_mark_as_used

Nombre

mca_mark_as_used --  pide un dispositivo MCA

Argumentos

slot

slot a pedir

FIXME

deber�amos hacer esto seguro para los threads

Pide un slot MCA para un controlador de dispositivo. Si el slot ya est� tomado la funci�n retorna 1, si no est� tomado es pedido y es devuelto un 0.

mca_mark_as_unused

Nombre

mca_mark_as_unused --  libera un dispositivo MCA

Argumentos

slot

slot a pedir

Descripci�n

Libera el slot para que otros controladoras lo usen.

mca_get_adapter_name

Nombre

mca_get_adapter_name --  obtiene la descripci�n del adaptador

Argumentos

slot

slot al que preguntar

Descripci�n

Retorna la descripci�n del adaptador si est� establecida. Si no ha sido establecida o el slot est� fuera de rango entonces devuelve NULL.

mca_isadapter

Nombre

mca_isadapter --  chequea si el slot mantiene un adaptador

Argumentos

slot

slot al que preguntar

Descripci�n

Retorna cero si el slot no mantiene un adaptador, distinto de cero si lo mantiene.

mca_isenabled

Nombre

mca_isenabled --  chequa si el slot mantiene un adaptador

Argumentos

slot

slot al que preguntar

Descripci�n

Retorna un valor distinto de cero si el slot mantiene un adaptador habilitado y cero para cualquier otro caso.


Cap�tulo 4. Funciones DMA Suministradas

mca_enable_dma

Nombre

mca_enable_dma --  canal en el que habilitar el DMA

Argumentos

dmanr

canal DMA

Descripci�n

Habilita en el bus MCA el DMA en un canal. Puede ser llamado desde un contexto IRQ.

mca_disable_dma

Nombre

mca_disable_dma --  canal en el que deshabilitar el DMA

Argumentos

dmanr

canal DMA

Descripci�n

Habilita en el bus MCA el DMA en un canal. Puede ser llamado desde un contexto IRQ.

mca_set_dma_addr

Nombre

mca_set_dma_addr --  carga una direcci�n DMA de 24 bits

Argumentos

dmanr

canal DMA

a

direcciones de bus de 24 bits

Descripci�n

Carga los registros de direcciones en el controlador DMA. Esto tiene una limitaci�n de 24 bits (16Mb).

mca_get_dma_addr

Nombre

mca_get_dma_addr --  carga una direcci�n DMA de 24 bits

Argumentos

dmanr

canal DMA

Descripci�n

Lee los registros de direcciones en el controlador DMA. Esto ten�a una limitaci�n de 24 bits (16Mb). El retorno es una direcci�n del bus.

mca_set_dma_count

Nombre

mca_set_dma_count --  carga una cuenta de transferencia de 16 bits

Argumentos

dmanr

canal DMA

count

count

Descripci�n

Establece la cuenta DMA para este canal. Esto puede ser hasta 64Kbytes. Estableciendo una cuenta a cero no har� lo que esperas.

mca_get_dma_residue

Nombre

mca_get_dma_residue --  obtiene los bytes que quedan por transferir

Argumentos

dmanr

canal DMA

Descripci�n

Esta funci�n retorna el n�mero de bytes que quedan por transferir en este canal DMA.

mca_set_dma_io

Nombre

mca_set_dma_io --  establece el puerto para una transferencia de E/S

Argumentos

dmanr

canal DMA

io_addr

un n�mero de puerto de E/S

Descripci�n

A diferencia de los controladores DMA del bus ISA un bus MCA puede transferir con un puerto de E/S de destino.

mca_set_dma_mode

Nombre

mca_set_dma_mode --  establece el modo de DMA

Argumentos

dmanr

canal DMA

mode

modo a establecer

Descripci�n

El controlador DMA soporta varios modos. Los modos que puedes tener son

set are

MCA_DMA_MODE_READ para leer de un dispositivo DMA.

MCA_DMA_MODE_WRITE para escribir al dispositivo DMA.

MCA_DMA_MODE_IO para hacer DMA a o desde un puerto de E/S.

MCA_DMA_MODE_16 para hacer transferencias de 16 bits.


Cap�tulo 5. Sobre la Traducci�n

Este documento es la traducci�n de "MCA Driver Programming Interface", documento que acompa�a al c�digo del n�cleo de Linux, versi�n 2.4.18.

Este documento ha sido traducido por Rub�n Melc�n ; y es publicado por el Proyecto Lucas

Versi�n de la traduci�n 0.04 ( Julio de 2002 ).

Si tienes comentarios sobre la traducci�n, ponte en contacto con Rub�n Melc�n

Done.