= GIET-VM / NIC Driver = 

[[PageOutline]]

The [source:soft/giet_vm/giet_drivers/nic_driver.c nic_driver.c] and [source:soft/giet_vm/giet_drivers/nic_driver.h nic_driver.h] files define the NIC driver. 

This component is a multi-channels, giga-bit Ethernet network controller. It is an ''external'', non replicated peripheral. 

 * The ''_nic_sync_send()'' and ''_nic_sync_receive()'' functions use a ''physical_memcpy()''  to transfer data between a single container (4 Kbytes buffer) in user space and the NIC internal chained buffer. They are blocking until completion of the transfer. One NIC channel must be allocated to the calling task in the mapping.
 
 * The ''_nic_cma_start_send()'' and ''_nic_cma_start_receive()'' functions use the ''vci_chbuf_dma'' component to transfer a flow of packets between a chained buffer in kernel space and the NIC internal chained buffer. They are non blocking. One NIC channel and two CMA channels (TX  and RX) must be allocated to the calling task in the mapping. 

All these access functions return -1 in case of error (illegal arguments).

The SEG_NIC_BASE address and the NB_NIC_CHANNELS parameter must be defined in the hard_config.h file.

The addressable registers map is defined [source:soft/giet_vm/giet_drivers/nic_driver.h here].

== __Initialization Functions__ ==

 === int '''_nic_global_init'''( unsigned int channels, unsigned int vis, unsigned int bc_enable, unsigned int bypass_enable ) ===
This function initializes the NIC global registers.
 * '''channels''' : number of active channels 
 * '''vis''' : bit vector(one bit per active channel)
 * '''bc_enable''' : broadcast packets accepted if non zero
 * '''bypass_enable''' : TX -> RX bypass supported if non zero
This function is used only by the boot code, and return always 0.

 === int '''_nic_channel_init'''( unsigned int index,  unsigned int mac4,  unsigned int mac2 ) ===
This function initializes the NIC registers for a given channel.
 * '''index''' : channel index
 * '''mac4''' : 32 LSB bits of the MAC address.
 * '''mac2''' : 16 MSB bits of the MAC address.
This function is used only by the boot code, and return always 0. 

== __Blocking functions using a physical_memcpy__ ==

 === int '''_nic_sync_send'''( unsigned int channel,  unsigned long long user_paddr ) ===
This blocking function uses a physical_memcpy() to transfer one container (4 Kbytes) from a single user buffer to the NIC channel allocated to the calling task. 
 * '''channel''' : NIC channel index
 * '''user_paddr''':  user buffer physical base address
Return 0 in case of success. Return -1 if buffer not mapped or not user accessible.

 === int '''_nic_sync_receive'''( unsigned int channel,  unsigned long long user_paddr ) ===
This blocking function uses a physical_memcpy() to transfer one container (4 Kbytes) from the NIC channel allocated to the calling task, to a single user buffer. 
 * '''channel''' : NIC channel index
 * '''user_paddr''':  user buffer physical base address
Return 0 in case of success. Return -1 if buffer not mapped or not user accessible.

== __Non blocking functions using the chained buffer DMA__ ==

 === int '''_nic_cma_send'''( unsigned int nic_channel,  unsigned int cma_channel,  chbuf_descriptor_t* chbuf ) ===
 This non blocking funtion starts a CMA channel to transfer a flow of containers from a NIC_RX chbuf to a kernel chbuf. 
 * '''nic_channel''' : NIC_RX channel index
 * '''cma_channel''' : CMA channel index
 * '''chbuf'''       : pointer on chbuf in kernel memory 
 The NIC channel is supposed to be already initialized.

Return 0 in case of success. Return -1 if NIC or CMA channel index too large.

=== int '''_nic_cma_receive'''(  unsigned int nic_channel,  unsigned int cma_channel,  chbuf_descriptor_t* chbuf ) ===
This non blocking funtion starts a CMA channel to transfer a flow of containers from a NIC_RX chbuf to a kernel chbuf. 
 * '''nic_channel''' : NIC_RX channel index
 * '''cma_channel''' : CMA channel index
 * '''chbuf'''       : pointer on chbuf in kernel memory 
The NIC channel is supposed to be already initialized.

Return 0 in case of success. Return -1 if NIC or CMA channel index too large.

== __ Interrupt Service Routines__ ==

 === void '''_nic_rx_isr'''( unsigned int irq_type,  unsigned int irq_id,  unsigned int channel ) ===
This interrupt Service Routine  handles IRQs from a NIC_RX channel.
WARNING : Not fully implemented yet : no IRQ acknowledge...

 === void '''_nic_tx_isr'''( unsigned int irq_type,  unsigned int irq_id,  unsigned int channel ) ===
This interrupt Service Routine  handles IRQs from a NIC_TX channel.
WARNING : Not fully implemented yet : no IRQ acknowledge...