KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Adding your own wishbone device

First define a short name for your device.

For example, using a fictional transporter, we can use the name transp

Then follow these steps:

  1. First step is to declare the base offset of the device in memory. For this we declare a macro named <DEV_NAME>_BASE, all in capitals. For our transporter this would amount to:
    #define TRANSP_BASE (0x00020800UL) // StarTrek Transporter
  2. The next step is to create a struct representing the device registers. This should be done in a file named dev_<dev_name>.h in the platform/lm32soc directory, or the transporter this would be dev_transp.h. This structure should be named <DEV_NAME>_Device.
    typedef struct
    {
    // ... register definitions
    Declare all important defines and the device structure. For this special types have been defined named reg_i, reg_o and reg_io, depending on whether its read-only, write-only or read/write respectively. Also all important register bits and such must be defined here as macros. All macro's should be prefixed by the capital short name and register name. Bits are defined simply like this: #define TRANSP_CMD_RESET BIT(2) defines the reset bit (no. 2) in the CMD register of our fictional transporter device. Ranges must have a shift and a mask: #define TRANSP_CFG_TXPOWER_MASK 0xFF00 and #define TRANSP_CFG_TXPOWER_SIHFT 16. Below follows a complete example:
    /**
    * @file
    *
    * dev_transp.h - StarTrek transporter device
    *
    * Please read the manual. Incorrect configuration could cause loss of limbs.
    */
    #include "dev_defs.h" ///< Defines registers and the BIT macro.
    #define TRANSP_STS_HEISENBC_OK BIT(0) ///< If set, Heisenberg compensators are ok.
    #define TRANSP_STS_IN_TRANSPORT BIT(1) ///< If set a transport is in progress.
    #define TRANSP_STS_IS_POWERED BIT(2) ///< Transported powered
    #define TRANSP_CMD_TRANSPORT BIT(0) ///< When set initiates transport
    #define TRANSP_CMD_RETRIEVE BIT(1) ///< When set beams from the coordinate to the pads.
    #define TRANSP_CMD_RESET BIT(2) ///< Resets the transporter. Do not set in transport!
    #define TRANSP_CFG_HEISENB_MASK 0x00FF0000 ///< Heisenberg quantum tweak factors mask
    #define TRANSP_CFG_HEISENB_SHIFT 24 ///< Heisenberg quantum tweak factors shift
    #define TRANSP_CFG_TXPOWER_MASK 0x0000FF00 ///< Configure transporter TX power mask
    #define TRANSP_CFG_TXPOWER_SHIFT 16 ///< Configure transporter TX power shift
    #define TRANSP_CFG_RXPOWER_MASK 0x000000FF ///< Configure transporter RX power mask
    #define TRANSP_CFG_RXPOWER_SHIFT 0 ///< Configure transporter RX power mask
    #define TRANSP_CRD_MIN -30000 ///< Minimum coordinate displacement
    #define TRANSP_CRD_MAX 30000 ///< Maximum coordinate displacement
    /**
    * Structure defines FutureDevices StarTrek transporter
    */
    typedef struct
    {
    reg_io CRD_X; ///< X displacement coordinate in meters (signed)
    reg_io CRD_Y; ///< Y displacement coordinate in meters (signed)
    reg_io CRD_Z; ///< Z displacement coordinate in meters (signed)
    reg_i STS; ///< Status
    reg_io CFG; ///< Configure
    reg_o CMD; ///< Command
  3. Once you have created your device structure. Add the device mapping in dev_soc.h:
    #define TRANSP ((TRANSP_Device *)TRANSP_BASE) ///< Transporter base pointer.

This concludes the adding of a wishbone device. The next step would be to create an actual driver. Currently this tutorial does not exist yet. Please refer to the source code of other drivers located at platform/drv/ for examples.