Changes between Version 2 and Version 3 of TBR/UserManual/DriverManager

Timestamp:

02/25/09 15:53:36 (15 years ago)

Author:

Hellstrom

Comment:

TBR/UserManual/DriverManager

@@ -11 +11 @@
 
 The purpose of the Driver Manager is mainly,
- * more easily reuse driver code
- * enable drivers to be written independent of how certain sevices are implemented.
-    - interrupt handling (registeration, masking, unmasking, acknowledging)
-    - memory space translation
- * Unify the way drivers are configured. The driver registration string is replaced.
- * build images suitable for multiple targets with different hardware present.
- * Hardware topology awareness.
- * Easier to access which drivers are loaded and what hardware is present.
- * An initial step towards an architecture independent PCI layer.
+ *  more easily reuse driver code
+ *  enable drivers to be written independent of how certain services are implemented.
+  *  interrupt handling (registration, masking, unmasking, acknowledging)
+  *  memory space translation
+  *  Bus information (Bus frequency, Snooping/Cache options)
+ *  Unify the way drivers are configured. The driver registration string is replaced.
+ *  build images suitable for multiple targets with different hardware present.
+ *  Hardware topology awareness.
+ *  Easier to access which drivers are loaded and what hardware is present.
+ *  An initial step towards an architecture independent PCI layer.
 =  Overview  =
 
@@ -89 +90 @@
         struct rtems_drvmgr_bus_ops     *ops;           /*!< Bus operations supported by this bus driver */
         int                             dev_cnt;        /*!< Number of devices this bus has */
-        struct bus_res_node             *reslist;       /*!< Bus resources, head of a linked list of resources. */
-        struct bus_mmap_entry           *mmaps;         /*!< Memory Map Translation, array of address spaces */
-};
+        struct rtems_drvmgr_bus_res     *reslist;       /*!< Bus resources, head of a linked list of resources. */
+        struct rtems_drvmgr_mmap_entry  *mmaps;         /*!< Memory Map Translation, array of address spaces */
+};
+
 }}}
 =  Root bus driver  =
@@ -195 +197 @@
 
 /*! Union of different values */
-union key_value {
+union rtems_drvmgr_key_value {
         unsigned int            i;              /*!< Key data type UNIGNED INTEGER */
         char                    *str;           /*!< Key data type STRING */
@@ -201 +203 @@
 };
 
-/* One key. Holding information relevant to the driver. */
-struct drv_res_key {
-        char                    *key_name;      /* Name of key */
-        int                     key_type;       /* How to interpret key_value */
-        union key_value         key_value;      /* The value or pointer to the value */
-};
-
-/*! Bus resource entry, Driver resources for a certain device instance, containing a number of keys 
+/* One key. One Value. Holding information relevant to the driver. */
+struct rtems_drvmgr_key {
+        char                            *key_name;      /* Name of key */
+        int                             key_type;       /* How to interpret key_value */
+        union rtems_drvmgr_key_value    key_value;      /* The value or pointer to the value */
+};
+
+/*! Driver resource entry, Driver resources for a certain device instance, containing a number of keys 
  * Where each key hold the data of interest.
  */
-struct drv_res {
+struct rtems_drvmgr_drv_res {
         unsigned long long      drv_id;         /*!< Identifies the driver this resource is aiming */
         int                     minor_bus;      /*!< Indentifies a specfic device */
-        struct drv_res_key      *keys;          /*!< First key in key array */
+        struct rtems_drvmgr_key *keys;          /*!< First key in key array, ended with KEY_EMPTY */
 };
 
 /*! Bus resource list node */
-struct bus_res_node {
-        struct bus_res_node     *next;          /*!< Next resource node in list */
-        struct drv_res          *resource;      /*!< Array of resources, one per device instance */
-};
+struct rtems_drvmgr_bus_res {
+        struct rtems_drvmgr_bus_res     *next;          /*!< Next resource node in list */
+        struct rtems_drvmgr_drv_res     *resource;      /*!< Array of resources, one per device instance */
+};
+
 }}}
 
+User defined Driver resources for the first three GRSPW cores. GRSPW core 1 and 2 uses the same configuration.
 {{{
 /* GRSPW0 resources */
-struct drv_res_key grlib_grspw0_res[] =
+struct rtems_drvmgr_key grlib_grspw0_res[] =
 
 {
@@ -233 +237 @@
         KEY_EMPTY
 };
-/* GRSPW1 resources */
-struct drv_res_key grlib_grspw1_res[] =
+/* GRSPW1 and GRSPW2 resources */
+struct rtems_drvmgr_key grlib_grspw1_res[] =
 
 {
@@ -242 +246 @@
 };
 /* GRLIB Plug & Play bus driver resources */
-struct drv_res grlib_drv_resources[] =
+struct rtems_drvmgr_drv_res grlib_drv_resources[] =
 
 {
         {DRIVER_AMBAPP_GAISLER_GRSPW_ID, 0, &grlib_grspw0_res[0]},
         {DRIVER_AMBAPP_GAISLER_GRSPW_ID, 1, &grlib_grspw1_res[0]},
+        {DRIVER_AMBAPP_GAISLER_GRSPW_ID, 2, &grlib_grspw1_res[0]},
         RES_EMPTY
 };
@@ -260 +265 @@
 
 The following may be configured,
- - Driver resources per bus.
+ - Driver resources per bus
  - Root bus driver
- - Driver table.
+ - Driver table
 
 The driver manager is configured by selecting drivers used by the driver manager and by
@@ -411 +416 @@
         void *src_address,
         void **dst_address);
+
+/*! Get key value from the bus resources matching [device[drv_id, minor_bus], key name, key type] 
+ * if no matching key NULL is returned.
+ *
+ * This is typically used by device drivers to find a particular device resource.
+ *
+ * \param dev         The device to search resource for.
+ * \param key_name    The key name to search for
+ * \param key_type    The key type expected.
+ * \return            Returns NULL if no value found matching Key Name and Key Type was found for device.
+ */
+extern union rtems_drvmgr_key_value *rtems_drvmgr_dev_key_get(
+        struct rtems_drvmgr_dev_info *dev,
+        char *key_name,
+        int key_type);
+
+}}}
+=  Driver skeleton  =
+
+
+Below is a selection from the GRSPW driver on how to create a driver using the Driver Manager structure. Below
+is also a sniplet from AMBA PnP the bus driver that the GRSPW driver is intended for.
+
+{{{
+/*  General part of a AMBA Plug & Play bus driver. */
+
+#define DRIVER_AMBA_ID(vendor, device, subid) \
+        DRIVER_SUBID_ADD((((unsigned long long)(vendor)<<32) | ((unsigned long long)(device))), subid)
+
+/*** Gaisler Hardware Device Driver definitions ***/
+#define DRIVER_AMBAPP_GAISLER_GRETH_ID          DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_ETHMAC, 0)
+#define DRIVER_AMBAPP_GAISLER_GRETH_ID_ALL      DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_ETHMAC, -1)
+
+#define DRIVER_AMBAPP_GAISLER_GRSPW_ID          DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_SPW, 0)
+#define DRIVER_AMBAPP_GAISLER_GRSPW_ID_ALL      DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_SPW, -1)
+
+#define DRIVER_AMBAPP_GAISLER_GRCAN_ID          DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_GRCAN, 0)
+#define DRIVER_AMBAPP_GAISLER_GRCAN_ID_ALL      DRIVER_AMBA_ID(VENDOR_GAISLER, GAISLER_GRCAN, -1)
+
+/*** ESA Hardware Device Driver definitions ***/
+#define DRIVER_AMBAPP_ESA_MCTRL_ID              DRIVER_AMBA_ID(VENDOR_ESA, ESA_MCTRL, 0)
+#define DRIVER_AMBAPP_ESA_MCTRL_ID_ALL          DRIVER_AMBA_ID(VENDOR_ESA, ESA_MCTRL, -1)
+#define DRIVER_AMBAPP_MCTRL_ID                  DRIVER_AMBAPP_ESA_MCTRL_ID
+#define DRIVER_AMBAPP_MCTRL_ID_ALL              DRIVER_AMBAPP_ESA_MCTRL_ID_ALL
+
+struct amba_dev_id {
+        unsigned short          vendor;
+        unsigned short          device;
+        /* Version ? */
+};
+
+struct amba_drv_info {
+        struct rtems_drvmgr_drv_info    general;        /* General bus info */
+        /* AMBA specific bus information */
+        struct amba_dev_id              *ids;           /* Supported hardware */
+};
+
+struct amba_dev_info {
+        struct amba_dev_id      id;
+        struct ambapp_dev_info  info;
+};
+}}}
+
+{{{
+#define GRSPW_DRIVER_TABLE_ENTRY \
+  { grspw_initialize, \
+    grspw_open, \
+    grspw_close, \
+    grspw_read, \
+    grspw_write, \
+    grspw_control }
+
+static rtems_driver_address_table grspw_driver = GRSPW_DRIVER_TABLE_ENTRY;
+static int grspw_driver_io_registered = 0;
+static rtems_device_major_number grspw_driver_io_major = 0;
+
+/******************* Driver manager interface ***********************/
+
+/* Driver prototypes */
+int grspw_register_io(rtems_device_major_number *m);
+int grspw_device_init(GRSPW_DEV *pDev);
+
+rtems_status_code grspw_init1(struct rtems_drvmgr_dev_info *dev);
+rtems_status_code grspw_init2(struct rtems_drvmgr_dev_info *dev);
+
+/* Driver operations */
+struct rtems_drvmgr_drv_ops grspw_ops = 
+{
+        grspw_init1,
+        grspw_init2,
+        NULL            /* Driver does not support device unregister (delete) */
+};
+
+/* Supported Hardware, Two different cores, however GRSPW2 is backwards compatible 
+ * except for some small details.
+ */
+struct amba_dev_id grspw_ids[] = 
+{
+        {VENDOR_GAISLER, GAISLER_SPW},
+        {VENDOR_GAISLER, GAISLER_SPW2},
+        {0, 0}          /* Mark end of table */
+};
+
+struct amba_drv_info grspw_drv_info =
+
+{
+        /* General Driver Part that all drivers must define */
+        {
+                NULL,                           /* Next driver */
+                NULL,                           /* Device list */
+                DRIVER_AMBAPP_GAISLER_GRSPW_ID, /* Driver ID */
+                "GRSPW_DRV",                    /* Driver Name */
+                DRVMGR_BUS_TYPE_AMBAPP,         /* Bus Type */
+                &grspw_ops,                     /* Driver oprtations supported */
+                0,                              /* No devices yet */
+        },
+        /* AMBA PnP Specific Driver Part that all AMBA PnP drivers must define */
+        &grspw_ids[0]
+};
+
+void grspw_register_drv (void)
+{
+        SPACEWIRE_DBG("Registering GRSPW driver\n");
+        rtems_drvmgr_drv_register(&grspw_drv_info.general);
+}
+
+rtems_status_code grspw_init1(struct rtems_drvmgr_dev_info *dev)
+{
+        GRSPW_DEV *priv;
+
+        SPACEWIRE_DBG("GRSPW[%d] on bus %s\n", dev->minor_drv, dev->parent->dev->name);
+        priv = dev->priv = malloc(sizeof(GRSPW_DEV));
+        if ( !priv )
+                return RTEMS_NO_MEMORY;
+        memset(priv, 0, sizeof(*priv));
+        priv->dev = dev;
+
+        /* This core will not find other cores, so we wait for init2() */
+
+        return RTEMS_SUCCESSFUL;
+}
+
+rtems_status_code grspw_init2(struct rtems_drvmgr_dev_info *dev)
+{
+        GRSPW_DEV *priv;
+        char prefix[16];
+        rtems_status_code status;
+
+        priv = dev->priv;
+
+        /* Do initialization */
+
+        if ( grspw_driver_io_registered == 0) {
+                /* Register the I/O driver only once for all cores */
+                if ( grspw_register_io(&grspw_driver_io_major) ) {
+                        /* Failed to register I/O driver */
+                        free(dev->priv);
+                        dev->priv = NULL;
+                        return RTEMS_UNSATISFIED;
+                }
+
+                grspw_driver_io_registered = 1;
+        }
+
+        /* I/O system registered and initialized 
+         * Now we take care of device initialization.
+         */
+
+        /* Get Bus frequency in Hz. The SpaceWire core is clocked by the bus */
+        if ( rtems_drvmgr_get_freq(dev, &priv->core_freq_khz) ) {
+                return RTEMS_UNSATISFIED;
+        }
+        /* Convert from Hz -> kHz */
+        priv->core_freq_khz = priv->core_freq_khz / 1000;
+
+        /* Initialize Device */
+        if ( grspw_device_init(priv) ) {
+                return RTEMS_UNSATISFIED;
+        }
+
+        /* Get Filesystem name prefix, this is to separate GRSPW cores by bus,
+         * This might not always be wanted.
+         */
+        prefix[0] = '\0';
+        if ( rtems_drvmgr_get_dev_prefix(dev, prefix) ) {
+                /* Failed to get prefix, make sure of a unique FS name
+                 * by using the driver minor.
+                 */
+                sprintf(priv->devName, "/dev/grspw%d", dev->minor_drv);
+        } else {
+                /* Got special prefix, this means we have a bus prefix
+                 * And we should use our "bus minor"
+                 */
+                sprintf(priv->devName, "/dev/%sgrspw%d", prefix, dev->minor_bus);
+        }
+
+        /* Register Device */
+        status = rtems_io_register_name(priv->devName, grspw_driver_io_major, dev->minor_drv);
+        if (status != RTEMS_SUCCESSFUL) {
+                return status;
+        }
+
+        return RTEMS_SUCCESSFUL;
+}
+
+/******************* Driver Implementation ***********************/
+
+int grspw_register_io(rtems_device_major_number *m)
+{
+        rtems_status_code r;
+
+        if ((r = rtems_io_register_driver(0, &grspw_driver, m)) == RTEMS_SUCCESSFUL) {
+                SPACEWIRE_DBG("GRSPW driver successfully registered, major: %d\n", *m);
+        } else {
+                switch(r) {
+                case RTEMS_TOO_MANY:
+                        printk("GRSPW rtems_io_register_driver failed: RTEMS_TOO_MANY\n");
+                        return -1;
+                case RTEMS_INVALID_NUMBER:  
+                        printk("GRSPW rtems_io_register_driver failed: RTEMS_INVALID_NUMBER\n");
+                        return -1;
+                case RTEMS_RESOURCE_IN_USE:
+                        printk("GRSPW rtems_io_register_driver failed: RTEMS_RESOURCE_IN_USE\n");
+                        return -1;
+                default:
+                        printk("GRSPW rtems_io_register_driver failed\n");
+                        return -1;
+                }
+        }
+        return 0;
+}
+
+int grspw_device_init(GRSPW_DEV *pDev)
+{
+        struct amba_dev_info *ambadev;
+        struct ambapp_dev_info *pnpinfo;
+        union rtems_drvmgr_key_value *value;
+
+        /* Get device information from AMBA PnP information */
+        ambadev = (struct amba_dev_info *)pDev->dev->businfo;
+        if ( ambadev == NULL ) {
+                return -1;
+        }
+        pnpinfo = &ambadev->info;
+        pDev->irq = pnpinfo->irq;
+        pDev->regs = (LEON3_SPACEWIRE_Regs_Map *)pnpinfo->apb_slv->start;
+        pDev->minor = pDev->dev->minor_drv;
+
+        /* Get SpaceWire core version */
+        switch( pnpinfo->device ) {
+                case GAISLER_SPW:
+                        pDev->core_ver = 1;
+                        break;
+                case GAISLER_SPW2:
+                        pDev->core_ver = 2;
+                        break;
+                default:
+                        return -1;
+        }
+
+        /* initialize the code with some resonable values,
+         * actual initialization is done later using ioctl(fd)
+         * on the opened device */
+        pDev->config.rxmaxlen = SPACEWIRE_RXPCK_SIZE;
+        pDev->txdbufsize = SPACEWIRE_TXD_SIZE;
+        pDev->txhbufsize = SPACEWIRE_TXH_SIZE;
+        pDev->rxbufsize = SPACEWIRE_RXPCK_SIZE;
+        pDev->txbufcnt = SPACEWIRE_TXBUFS_NR;
+        pDev->rxbufcnt = SPACEWIRE_RXBUFS_NR;
+
+        pDev->ptr_rxbuf0 = 0;
+        pDev->ptr_txdbuf0 = 0;
+        pDev->ptr_txhbuf0 = 0;
+        pDev->rx_dma_area = 0;
+        pDev->tx_data_dma_area = 0;
+        pDev->tx_hdr_dma_area = 0;
+
+        /* Get Configuration from Bus resources (Let user override defaults) */
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "txBdCnt", KEY_TYPE_INT);
+        if ( value )
+                pDev->txbufcnt = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "rxBdCnt", KEY_TYPE_INT);
+        if ( value )
+                pDev->rxbufcnt = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "txDataSize", KEY_TYPE_INT);
+        if ( value )
+                pDev->txdbufsize = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "txHdrSize", KEY_TYPE_INT);
+        if ( value )
+                pDev->txhbufsize = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "rxPktSize", KEY_TYPE_INT);
+        if ( value )
+                pDev->rxbufsize = value->i;
+        
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "rxDmaArea", KEY_TYPE_INT);
+        if ( value )
+                pDev->rx_dma_area = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "txDataDmaArea", KEY_TYPE_INT);
+        if ( value )
+                pDev->tx_data_dma_area = value->i;
+
+        value = rtems_drvmgr_dev_key_get(pDev->dev, "txHdrDmaArea", KEY_TYPE_INT);
+        if ( value )
+                pDev->tx_hdr_dma_area = value->i;
+
+        if (grspw_buffer_alloc(pDev)) 
+                return RTEMS_NO_MEMORY;
+
+        /* Create semaphores */
+        rtems_semaphore_create(
+                rtems_build_name('T', 'x', 'S', '0' + pDev->minor), 
+                0, 
+                RTEMS_FIFO | RTEMS_SIMPLE_BINARY_SEMAPHORE | RTEMS_NO_INHERIT_PRIORITY | \
+                RTEMS_NO_PRIORITY_CEILING, 
+                0, 
+                &(pDev->txsp));
+
+        rtems_semaphore_create(
+                rtems_build_name('R', 'x', 'S', '0' + pDev->minor), 
+                0, 
+                RTEMS_FIFO | RTEMS_SIMPLE_BINARY_SEMAPHORE | RTEMS_NO_INHERIT_PRIORITY | \
+                RTEMS_NO_PRIORITY_CEILING, 
+                0, 
+                &(pDev->rxsp));
+
+        grspw_hw_init(pDev);
+
+        /* Register interrupt routine */
+        if ( rtems_drvmgr_interrupt_register(pDev->dev, 0, grspw_interrupt, pDev) ) {
+                return -1;
+        }
+
+        return 0;
+}
+
+/* IOCTL */
+static rtems_device_driver grspw_control(
+        rtems_device_major_number major,
+        rtems_device_minor_number minor,
+        void                * arg
+        )
+{
+        int timeout;
+        rtems_device_driver ret;
+        rtems_libio_ioctl_args_t *ioarg = (rtems_libio_ioctl_args_t *) arg;
+        GRSPW_DEV *pDev;
+        struct rtems_drvmgr_dev_info *dev;
+
+        SPACEWIRE_DBGC(DBGSPW_IOCALLS, "ctrl [%i,%i]\n", major, minor);
+
+        /* Get device pointer by searching in driver list for matching driver minor, 
+         * it would be better if RTEMS delivered the device pointer when calling
+         * grspw_control...
+         */
+        if ( rtems_drvmgr_get_dev(&grspw_drv_info.general, minor, &dev) ) {
+                return RTEMS_INVALID_NAME;
+        }
+        pDev = (GRSPW_DEV *)dev->priv;
+
+        if (!ioarg)
+                return RTEMS_INVALID_NAME;
+
+        ioarg->ioctl_return = 0;
+        switch(ioarg->command) {
+                case SPACEWIRE_IOCTRL_START:
+                        if ( pDev->running ){
+                                return RTEMS_INVALID_NAME;
+                        }
+
+                        /* Get timeout from userspace
+                         *  timeout:
+                         *   ¤  -1         = Default timeout
+                         *   ¤  less than -1 = forever
+                         *   ¤  0           = no wait, proceed if link is up
+                         *   ¤  positive     = specifies number of system clock ticks that 
+                         *                   startup will wait for link to enter ready mode.
+                         */
+                        timeout = (int)ioarg->buffer;
+                        
+                        if ( (ret=grspw_hw_startup(pDev,timeout)) != RTEMS_SUCCESSFUL ) {
+                                return ret;
+                        }
+                        pDev->running = 1;
+                        /* Enable interrupt */
+                        rtems_drvmgr_interrupt_enable(dev, 0);
+                        break;
+
+                case SPACEWIRE_IOCTRL_STOP:
+                        if ( !pDev->running ){
+                                return RTEMS_INVALID_NAME;
+                        }
+                        /* Disable interrupts */
+                        rtems_drvmgr_interrupt_disable(dev, 0);
+
+                        pDev->running = 0;
+
+                        /* Stop Receiver and transmitter */
+                        grspw_hw_stop(pDev,1,1);
+                        break;
+
+                default:
+                        return RTEMS_NOT_IMPLEMENTED;
+        }
+
+        SPACEWIRE_DBGC(DBGSPW_IOCALLS, "SPW_IOCTRL Return\n");
+        return RTEMS_SUCCESSFUL;
+}
 }}}
 =  TODO  =
@@ -417 +835 @@
 
 Changes to BSPs:
- * Add support to BSP to register root bus
- * Make driver resources on the root bus weak so that the user can override them.
-= = RTEMS  ==
-
- * Make I/O Manager handle regestering I/O Drivers before I/O Manager is initialized.
-=  == Driver Manager ===
+ *  Add support to BSP to register root bus
+ *  Make driver resources on the root bus weak so that the user can override them.
+=  == RTEMS ===
+
+ *  Make I/O Manager handle registering I/O Drivers before I/O Manager is initialized.
+
+=== Driver Manager ===
 
  *  Initialize the Driver manager before I/O Manager initialization.
+ *  Write console/timer/IRQ driver