Changes between Version 2 and Version 3 of nic_device_api


Ignore:
Timestamp:
Jan 26, 2020, 10:33:30 PM (4 years ago)
Author:
alain
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • nic_device_api

    v2 v3  
    2020The WTI mailboxes used by the driver ro receive events from the NIC hardware (available RX packet, or free TX slot, for a given channel), must be statically allocated during the kernel initialisation phase, and must be routed to the cluster containing the associated device descriptor and server thread.
    2121
    22  Finally, the generic NIC device "kernel" API defines four command types, that are detailed in section C.
    23  * '''READABLE''' : returns true if at least one RX paquet is available in RX queue.
    24  * '''WRITABLE : returns true if at least one empty slot is available in TX queue.
    25  * '''READ'''     : consume one packet from the RX queue.
    26  * '''WRITE'''    : produce one packet to the TX queue.
     22The generic NIC device "kernel" API defines two functions:
     23* the '''read()''' function is called by the RX server thread to get one paquet from the RX queue.
     24* the '''write()''' function is called by the TX server thread to put one packet to the TX queue.
     25This "kernel" API is detailed in section C below.
    2726
    28 All RX or TX paquets are sent or received in standard 2 Kbytes kernel buffers, that are dynamically allocated by the protocols stack. The structure ''pkd_t'' defining a packet descriptor contains the buffer pointer and the actual Ethernet packet length in bytes.
     27All RX or TX paquets are sent or received in standard 2 Kbytes kernel buffers, that are dynamically allocated by the server threads. The structure ''pkd_t'' defining a packet descriptor contains the buffer pointer and the actual Ethernet packet length in bytes.
    2928
    30 The actual TX an RX queues structures depends on the hardware NIC implementation, and must be defined by the driver code.
     29The actual TX an RX queues structures depends on the hardware NIC implementation, and are defined by the driver code.
    3130
    32 To access the various drivers, the NIC device defines a lower-level "driver" API, that is detailed in section D below.
     31To access the drivers, the NIC device defines a lower-level "driver" API, containing four command types, that are detailed in section D below.
    3332
    3433All NIC device structures and access functions are defined in the [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_nic.c  dev_nic.c] et [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_nic.h dev_nic.h] files.
     34
     35== __B) Initialisation__ ==
     36
     37The '''dev_nic_init()''' function makes the following initializations for given NIC chdev:
     38 * It selects a core in cluster containing the N chdev to execute the  server thread.
     39 * it links the NIC IRQ to the core executing the server thread.
     40 * it initialises the NIC specific fields of the chdev descriptor.
     41 * it calls the nic_driver_init() function to initialize the NIC hardware device,
     42 * it initializes the specific software data structures required by the hardware implementation.
     43It must be called by a local thread.
     44
     45== __C) The "kernel" API__ ==
     46
     47The ''read'' function is always called by the DEV server thread associated to a given NIC_RX chdev. The ''write'' function is always called by the DEV server thread associated to a given NIC_TX chdev. For both functions, the local pointer on the chdev descriptor is registered in the server thread descriptor, and the channel index is registered in the chdev descriptor.
     48
     49These two functions are blocking and return only when the transfer is completed.
     50
     51* The '''dev_nic_read( pkd_t * pkd )''' read one Ethernet/IPv4 packet from the NIC_RX queue associated to the NIC channel. It calls directly the NIC driver, without registering in a waiting queue, because only one dedicated  NIC_RX thread can access a given NIC_RX queue.
     52 1. It test the NIC_RX queue status, using the NIC_CMD_READABLE driver command. If the NIC_RX queue is empty, it unmasks the NIC-RX_IRQ, blocks and deschedules. It is re-activated by the nic_driver_isr() function (activated by the NIC_RX_IRQ) as soon as the queue becomes not empty.
     53 1. If the queue is not empty, it get one packet, using the NIC_CMD_READ driver command and returns.
     54Both commands are successively registered in the NIC-RX server thread descriptor to be passed to the driver.
     55
     56WARNING : for a RX packet, the initiator is the NIC hardware, and the protocols stack executed by the RX thread is traversed upward, from the point of view of function calls.
     57
     58* The '''dev_nic_write( pkd_t * pkd )''' function writes one Ethernet/IPv4 packet to the NIC_TX queue associated to the NIC channel. It calls directly the NIC driver, without registering in a waiting queue, because only one dedicated NIC_TX thread can access this NIC_TX queue.
     59 1. It test the NIC_RX queue status, using the NIC_CMD_WRITABLE driver command. If the NIC_TX queue is full, it unmasks the NIC-TX_IRQ, blocks and deschedules. It is re-activated by the nic_driver_isr() function (activated by the NIC_TX_IRQ) as soon as the queue becomes not full.
     60 1. If the queue is not full, it put one packet, using the NIC_CMD_WRITE driver command.
     61Both commands are successively registered in the NIC-TX server thread descriptor to be passed to the driver.
     62
     63WARNING : for a TX packet, the initiator is the client thread, and the protocols stack executed by the TX thread is traversed downward, from the point of view of function calls.
     64
     65== __D) The "driver" API__ ==
     66
     67All NIC drivers must define three functions :
     68* void '''nic_driver_init( chdev_t * chdev )'''
     69* void '''nic_driver_cmd( xptr_t  thread_xp )'''
     70* void '''nic_driver_isr( chdev_t * chdev )'''
     71
     72The ''nic_driver_cmd()'' function arguments are actually defined in the ''nic_command_t'' structure embedded in the server thread descriptor. One command contains four informations:
     73 - '''type''' : operation type (defined below)
     74 - '''buffer''' : local pointer on kernel buffer containing one packet.
     75 - '''length''' : packet length (in bytes).
     76 - '''status''' : return value for READABLE and WRITABLE
     77
     78The four command types for the NIC driver(s) are the following:
     79 * '''NIC_CMD_READABLE''' : returns true if at least one RX paquet is available in RX queue.
     80 * '''NIC_CMD_WRITABLE''' : returns true if at least one empty slot is available in TX queue.
     81 * '''NIC_CMD_READ'''     : consume one packet from the RX queue.
     82 * '''NIC_CMD_WRITE'''    : produce one packet to the TX queue.
     83