Modules/SB16 - Stub driver, nowhere near complete

[tpg/acess2.git] / Kernel / include / tpl_drv_network.h

diff --git a/Kernel/include/tpl_drv_network.h b/Kernel/include/tpl_drv_network.h
index 5a702a2..6b7493a 100644 (file)
--- a/Kernel/include/tpl_drv_network.h
+++ b/Kernel/include/tpl_drv_network.h
@@ -1,7 +1,31 @@
 /**\r
  * \file tpl_drv_network.h\r
  * \brief Network Interface Driver Interface Definitions\r
-*/\r
+ * \r
+ * \section dirs VFS Layout\r
+ * All network drivers must have the following basic VFS structure\r
+ * The root of the driver will only contain files that are named from zero\r
+ * upwards that represent the present network adapters that this driver\r
+ * controls. All VFS nodes must implement ::eTplDrv_IOCtl with\r
+ * DRV_IOCTL_TYPE returning DRV_TYPE_NETWORK.\r
+ * The adapter nodes must also implement ::eTplNetwork_IOCtl fully\r
+ * (unless it is noted in the ::eTplNetwork_IOCtl documentation that a\r
+ * call is optional)\r
+ * \r
+ * \section files Adapter Files\r
+ * \subsection Reading\r
+ * When an adapter file is read from, the driver will block the reading\r
+ * thread until a packet arrives (if there is not already an unhandled\r
+ * packet in the queue) this will then be read into the destination buffer.\r
+ * If the packet does not fit in the buffer, the end of it is discarded.\r
+ * Likewise, if the packet does not completely fill the buffer, the call\r
+ * will still read to the buffer and then return the size of the packet.\r
+ * \subsection Writing\r
+ * When an adapter is written to, the data written is encoded as a packet\r
+ * and sent, if the data is not the correct size to be sent (if the packet\r
+ * is too small, or if it is too large) -1 should be returned and the packet\r
+ * will not be sent.\r
+ */\r
 #ifndef _TPL_NETWORK_H\r
 #define _TPL_NETWORK_H\r
 \r
@@ -16,10 +40,17 @@ enum eTplNetwork_IOCtl {
        /**\r
         * ioctl(..., Uint8 *MAC[6])\r
         * \brief Get the MAC address of the interface\r
+        * \return 1 on success, 0 if the file is the root, -1 on error\r
+        * \r
+        * Copies the six byte Media Access Control (MAC) address of the\r
+        * adapter to the \a MAC array.\r
        */\r
        NET_IOCTL_GETMAC = 4\r
 };\r
 \r
+/**\r
+ * \brief IOCtl name strings for use with eTplDrv_IOCtl.DRV_IOCTL_LOOKUP\r
+ */\r
 #define        DRV_NETWORK_IOCTLNAMES  "get_mac_addr"\r
 \r
 #endif\r