src/dev/arm/hdlcd.hh

   1 /*
   2  * Copyright (c) 2010-2013, 2015, 2017 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Redistribution and use in source and binary forms, with or without
  15  * modification, are permitted provided that the following conditions are
  16  * met: redistributions of source code must retain the above copyright
  17  * notice, this list of conditions and the following disclaimer;
  18  * redistributions in binary form must reproduce the above copyright
  19  * notice, this list of conditions and the following disclaimer in the
  20  * documentation and/or other materials provided with the distribution;
  21  * neither the name of the copyright holders nor the names of its
  22  * contributors may be used to endorse or promote products derived from
  23  * this software without specific prior written permission.
  24  *
  25  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  28  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  29  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  30  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  31  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  32  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  33  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  34  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  35  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38
  39 /** @file
  40  * Implementiation of the ARM HDLcd controller.
  41  *
  42  * This implementation aims to have sufficient detail such that underrun
  43  * conditions are reasonable / behave similar to reality.  There are two
  44  * 'engines' going at once.  First, the DMA engine running at LCD clock
  45  * frequency is responsible for filling the controller's internal buffer.
  46  * The second engine runs at the pixel clock frequency and reads the pixels
  47  * out of the internal buffer.  The pixel rendering engine uses front / back
  48  * porch and sync delays between lines and frames.
  49  *
  50  * If the pixel rendering engine does not have a pixel to display, it will
  51  * cause an underrun event.  The HDLcd controller, per spec, will stop
  52  * issuing DMA requests for the rest of the frame and resume normal behavior
  53  * on the subsequent frame.  What pixels are rendered upon an underrun
  54  * condition is different than the real hardware; while the user will see
  55  * artifacts (previous frame mixed with current frame), it is not the same
  56  * behavior as real hardware which repeats the last pixel value for the rest
  57  * of the current frame.  This compromise was made to save on memory and
  58  * complexity and assumes that it is not important to accurately model the
  59  * content of an underrun frame.
  60  *
  61  * KNOWN ISSUES
  62  * <ul>
  63  *   <li>The HDLcd is implemented here as an AmbaDmaDevice, but it
  64  *       doesn't have an AMBA ID as far as I know.  That is the only
  65  *       bit of the AmbaDmaDevice interface that is irrelevant to it,
  66  *       so a fake AMBA ID is used for now.  I didn't think inserting
  67  *       an extra layer of hierachy between AmbaDmaDevice and
  68  *       DmaDevice would be helpful to anyone else, but that may be
  69  *       the right answer.
  70  * </ul>
  71  */
  72
  73 #ifndef __DEV_ARM_HDLCD_HH__
  74 #define __DEV_ARM_HDLCD_HH__
  75
  76 #include <fstream>
  77 #include <memory>
  78
  79 #include "base/framebuffer.hh"
  80 #include "base/imgwriter.hh"
  81 #include "base/output.hh"
  82 #include "dev/arm/amba_device.hh"
  83 #include "dev/pixelpump.hh"
  84 #include "sim/serialize.hh"
  85
  86 class VncInput;
  87 struct HDLcdParams;
  88 class HDLcdPixelPump;
  89
  90 class HDLcd: public AmbaDmaDevice
  91 {
  92   public:
  93     HDLcd(const HDLcdParams &p);
  94     ~HDLcd();
  95
  96     void serialize(CheckpointOut &cp) const override;
  97     void unserialize(CheckpointIn &cp) override;
  98
  99     void drainResume() override;
 100
 101   public: // IO device interface
 102     Tick read(PacketPtr pkt) override;
 103     Tick write(PacketPtr pkt) override;
 104
 105     AddrRangeList getAddrRanges() const override { return addrRanges; }
 106
 107   protected: // Parameters
 108     VncInput *vnc;
 109     const bool workaroundSwapRB;
 110     const bool workaroundDmaLineCount;
 111     const AddrRangeList addrRanges;
 112     const bool enableCapture;
 113     const Addr pixelBufferSize;
 114     const Tick virtRefreshRate;
 115
 116   protected: // Register handling
 117     /** ARM HDLcd register offsets */
 118     enum RegisterOffset {
 119         Version          = 0x0000,
 120         Int_RawStat      = 0x0010,
 121         Int_Clear        = 0x0014,
 122         Int_Mask         = 0x0018,
 123         Int_Status       = 0x001C,
 124         Fb_Base          = 0x0100,
 125         Fb_Line_Length   = 0x0104,
 126         Fb_Line_Count    = 0x0108,
 127         Fb_Line_Pitch    = 0x010C,
 128         Bus_Options      = 0x0110,
 129         V_Sync           = 0x0200,
 130         V_Back_Porch     = 0x0204,
 131         V_Data           = 0x0208,
 132         V_Front_Porch    = 0x020C,
 133         H_Sync           = 0x0210,
 134         H_Back_Porch     = 0x0214,
 135         H_Data           = 0x0218,
 136         H_Front_Porch    = 0x021C,
 137         Polarities       = 0x0220,
 138         Command          = 0x0230,
 139         Pixel_Format     = 0x0240,
 140         Red_Select       = 0x0244,
 141         Green_Select     = 0x0248,
 142         Blue_Select      = 0x024C,
 143     };
 144
 145     /** Reset value for Bus_Options register */
 146     static constexpr size_t BUS_OPTIONS_RESETV = 0x408;
 147
 148     /** Reset value for Version register */
 149     static constexpr size_t VERSION_RESETV = 0x1CDC0000;
 150
 151     /** AXI port width in bytes */
 152     static constexpr size_t AXI_PORT_WIDTH = 8;
 153
 154     /** max number of beats delivered in one dma burst */
 155     static constexpr size_t MAX_BURST_LEN = 16;
 156
 157     /** Maximum number of bytes per pixel */
 158     static constexpr size_t MAX_PIXEL_SIZE = 4;
 159
 160     /**
 161      * @name RegisterFieldLayouts
 162      * Bit layout declarations for multi-field registers.
 163      */
 164     /**@{*/
 165     BitUnion32(VersionReg)
 166         Bitfield<7,0>   version_minor;
 167         Bitfield<15,8>  version_major;
 168         Bitfield<31,16> product_id;
 169     EndBitUnion(VersionReg)
 170
 171     static constexpr uint32_t INT_DMA_END = (1UL << 0);
 172     static constexpr uint32_t INT_BUS_ERROR = (1UL << 1);
 173     static constexpr uint32_t INT_VSYNC = (1UL << 2);
 174     static constexpr uint32_t INT_UNDERRUN = (1UL << 3);
 175
 176     BitUnion32(FbLineCountReg)
 177         Bitfield<11,0>  fb_line_count;
 178         Bitfield<31,12> reserved_31_12;
 179     EndBitUnion(FbLineCountReg)
 180
 181     BitUnion32(BusOptsReg)
 182         Bitfield<4,0>   burst_len;
 183         Bitfield<7,5>   reserved_7_5;
 184         Bitfield<11,8>  max_outstanding;
 185         Bitfield<31,12> reserved_31_12;
 186     EndBitUnion(BusOptsReg)
 187
 188     BitUnion32(TimingReg)
 189         Bitfield<11,0>  val;
 190         Bitfield<31,12> reserved_31_12;
 191     EndBitUnion(TimingReg)
 192
 193     BitUnion32(PolaritiesReg)
 194         Bitfield<0>    vsync_polarity;
 195         Bitfield<1>    hsync_polarity;
 196         Bitfield<2>    dataen_polarity;
 197         Bitfield<3>    data_polarity;
 198         Bitfield<4>    pxlclk_polarity;
 199         Bitfield<31,5> reserved_31_5;
 200     EndBitUnion(PolaritiesReg)
 201
 202     BitUnion32(CommandReg)
 203         Bitfield<0>    enable;
 204         Bitfield<31,1> reserved_31_1;
 205     EndBitUnion(CommandReg)
 206
 207     BitUnion32(PixelFormatReg)
 208         Bitfield<2,0>  reserved_2_0;
 209         Bitfield<4,3>  bytes_per_pixel;
 210         Bitfield<30,5> reserved_30_5;
 211         Bitfield<31>   big_endian;
 212     EndBitUnion(PixelFormatReg)
 213
 214     BitUnion32(ColorSelectReg)
 215         Bitfield<4,0>   offset;
 216         Bitfield<7,5>   reserved_7_5;
 217         Bitfield<11,8>  size;
 218         Bitfield<15,12> reserved_15_12;
 219         Bitfield<23,16> default_color;
 220         Bitfield<31,24> reserved_31_24;
 221     EndBitUnion(ColorSelectReg)
 222     /**@}*/
 223
 224     /**
 225      * @name HDLCDRegisters
 226      * HDLCD register contents.
 227      */
 228     /**@{*/
 229     const VersionReg version;       /**< Version register */
 230     uint32_t int_rawstat;           /**< Interrupt raw status register */
 231     uint32_t int_mask;              /**< Interrupt mask register */
 232     uint32_t fb_base;               /**< Frame buffer base address register */
 233     uint32_t fb_line_length;        /**< Frame buffer Line length register */
 234     FbLineCountReg fb_line_count;   /**< Frame buffer Line count register */
 235     int32_t fb_line_pitch;          /**< Frame buffer Line pitch register */
 236     BusOptsReg bus_options;         /**< Bus options register */
 237     TimingReg v_sync;               /**< Vertical sync width register */
 238     TimingReg v_back_porch;         /**< Vertical back porch width register */
 239     TimingReg v_data;               /**< Vertical data width register */
 240     TimingReg v_front_porch;        /**< Vertical front porch width register */
 241     TimingReg h_sync;               /**< Horizontal sync width register */
 242     TimingReg h_back_porch;         /**< Horizontal back porch width register */
 243     TimingReg h_data;               /**< Horizontal data width register */
 244     TimingReg h_front_porch;        /**< Horizontal front porch width reg */
 245     PolaritiesReg polarities;       /**< Polarities register */
 246     CommandReg command;             /**< Command register */
 247     PixelFormatReg pixel_format;    /**< Pixel format register */
 248     ColorSelectReg red_select;      /**< Red color select register */
 249     ColorSelectReg green_select;    /**< Green color select register */
 250     ColorSelectReg blue_select;     /**< Blue color select register */
 251     /** @} */
 252
 253     uint32_t readReg(Addr offset);
 254     void writeReg(Addr offset, uint32_t value);
 255
 256     PixelConverter pixelConverter() const;
 257     DisplayTimings displayTimings() const;
 258
 259     void createDmaEngine();
 260
 261     void cmdEnable();
 262     void cmdDisable();
 263
 264     bool enabled() const { return command.enable; }
 265
 266   public: // Pixel pump callbacks
 267     bool pxlNext(Pixel &p);
 268     void pxlVSyncBegin();
 269     void pxlVSyncEnd();
 270     void pxlUnderrun();
 271     void pxlFrameDone();
 272
 273   protected: // Interrupt handling
 274     /**
 275      * Assign new interrupt values and update interrupt signals
 276      *
 277      * A new interrupt is scheduled signalled if the set of unmasked
 278      * interrupts goes empty to non-empty. Conversely, if the set of
 279      * unmasked interrupts goes from non-empty to empty, the interrupt
 280      * signal is cleared.
 281      *
 282      * @param ints New <i>raw</i> interrupt status
 283      * @param mask New interrupt mask
 284      */
 285     void setInterrupts(uint32_t ints, uint32_t mask);
 286
 287     /**
 288      * Convenience function to update the interrupt mask
 289      *
 290      * @see setInterrupts
 291      * @param mask New interrupt mask
 292      */
 293     void intMask(uint32_t mask) { setInterrupts(int_rawstat, mask); }
 294
 295     /**
 296      * Convenience function to raise a new interrupt
 297      *
 298      * @see setInterrupts
 299      * @param ints Set of interrupts to raise
 300      */
 301     void intRaise(uint32_t ints) {
 302         setInterrupts(int_rawstat | ints, int_mask);
 303     }
 304
 305     /**
 306      * Convenience function to clear interrupts
 307      *
 308      * @see setInterrupts
 309      * @param ints Set of interrupts to clear
 310      */
 311     void intClear(uint32_t ints) {
 312         setInterrupts(int_rawstat & ~ints, int_mask);
 313     }
 314
 315     /** Masked interrupt status register */
 316     uint32_t intStatus() const { return int_rawstat & int_mask; }
 317
 318   protected: // Pixel output
 319     class PixelPump : public BasePixelPump
 320     {
 321       public:
 322         PixelPump(HDLcd &p, ClockDomain &pxl_clk, unsigned pixel_chunk)
 323             : BasePixelPump(p, pxl_clk, pixel_chunk), parent(p) {}
 324
 325         void dumpSettings();
 326
 327       protected:
 328         bool nextPixel(Pixel &p) override { return parent.pxlNext(p); }
 329
 330         void onVSyncBegin() override { return parent.pxlVSyncBegin(); }
 331         void onVSyncEnd() override { return parent.pxlVSyncEnd(); }
 332
 333         void onUnderrun(unsigned x, unsigned y) override {
 334             parent.pxlUnderrun();
 335         }
 336
 337         void onFrameDone() override { parent.pxlFrameDone(); }
 338
 339       protected:
 340         HDLcd &parent;
 341     };
 342
 343     /** Handler for fast frame refresh in KVM-mode */
 344     void virtRefresh();
 345     EventFunctionWrapper virtRefreshEvent;
 346
 347     /** Helper to write out bitmaps */
 348     std::unique_ptr<ImgWriter> imgWriter;
 349
 350     /** Image Format */
 351     Enums::ImageFormat imgFormat;
 352
 353     /** Picture of what the current frame buffer looks like */
 354     OutputStream *pic;
 355
 356     /** Cached pixel converter, set when the converter is enabled. */
 357     PixelConverter conv;
 358
 359     PixelPump pixelPump;
 360
 361   protected: // DMA handling
 362     class DmaEngine : public DmaReadFifo
 363     {
 364       public:
 365         DmaEngine(HDLcd &_parent, size_t size,
 366                   unsigned request_size, unsigned max_pending,
 367                   size_t line_size, ssize_t line_pitch, unsigned num_lines);
 368
 369         void startFrame(Addr fb_base);
 370         void abortFrame();
 371         void dumpSettings();
 372
 373         void serialize(CheckpointOut &cp) const override;
 374         void unserialize(CheckpointIn &cp) override;
 375
 376       protected:
 377         void onEndOfBlock() override;
 378         void onIdle() override;
 379
 380         HDLcd &parent;
 381         const size_t lineSize;
 382         const ssize_t linePitch;
 383         const unsigned numLines;
 384
 385         Addr nextLineAddr;
 386         Addr frameEnd;
 387     };
 388
 389     std::unique_ptr<DmaEngine> dmaEngine;
 390
 391   protected: // Statistics
 392     struct HDLcdStats: public Stats::Group
 393     {
 394         HDLcdStats(Stats::Group *parent);
 395         Stats::Scalar underruns;
 396     } stats;
 397 };
 398
 399 #endif