2 * Copyright (c) 2010-2013, 2015, 2017 ARM Limited
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.
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.
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.
37 * Authors: Chris Emmons
43 * Implementiation of the ARM HDLcd controller.
45 * This implementation aims to have sufficient detail such that underrun
46 * conditions are reasonable / behave similar to reality. There are two
47 * 'engines' going at once. First, the DMA engine running at LCD clock
48 * frequency is responsible for filling the controller's internal buffer.
49 * The second engine runs at the pixel clock frequency and reads the pixels
50 * out of the internal buffer. The pixel rendering engine uses front / back
51 * porch and sync delays between lines and frames.
53 * If the pixel rendering engine does not have a pixel to display, it will
54 * cause an underrun event. The HDLcd controller, per spec, will stop
55 * issuing DMA requests for the rest of the frame and resume normal behavior
56 * on the subsequent frame. What pixels are rendered upon an underrun
57 * condition is different than the real hardware; while the user will see
58 * artifacts (previous frame mixed with current frame), it is not the same
59 * behavior as real hardware which repeats the last pixel value for the rest
60 * of the current frame. This compromise was made to save on memory and
61 * complexity and assumes that it is not important to accurately model the
62 * content of an underrun frame.
66 * <li>The HDLcd is implemented here as an AmbaDmaDevice, but it
67 * doesn't have an AMBA ID as far as I know. That is the only
68 * bit of the AmbaDmaDevice interface that is irrelevant to it,
69 * so a fake AMBA ID is used for now. I didn't think inserting
70 * an extra layer of hierachy between AmbaDmaDevice and
71 * DmaDevice would be helpful to anyone else, but that may be
76 #ifndef __DEV_ARM_HDLCD_HH__
77 #define __DEV_ARM_HDLCD_HH__
82 #include "base/framebuffer.hh"
83 #include "base/imgwriter.hh"
84 #include "base/output.hh"
85 #include "dev/arm/amba_device.hh"
86 #include "dev/pixelpump.hh"
87 #include "sim/serialize.hh"
93 class HDLcd: public AmbaDmaDevice
96 HDLcd(const HDLcdParams *p);
99 void regStats() override;
101 void serialize(CheckpointOut &cp) const override;
102 void unserialize(CheckpointIn &cp) override;
104 void drainResume() override;
106 public: // IO device interface
107 Tick read(PacketPtr pkt) override;
108 Tick write(PacketPtr pkt) override;
110 AddrRangeList getAddrRanges() const override { return addrRanges; }
112 protected: // Parameters
114 const bool workaroundSwapRB;
115 const bool workaroundDmaLineCount;
116 const AddrRangeList addrRanges;
117 const bool enableCapture;
118 const Addr pixelBufferSize;
119 const Tick virtRefreshRate;
121 protected: // Register handling
122 /** ARM HDLcd register offsets */
123 enum RegisterOffset {
125 Int_RawStat = 0x0010,
130 Fb_Line_Length = 0x0104,
131 Fb_Line_Count = 0x0108,
132 Fb_Line_Pitch = 0x010C,
133 Bus_Options = 0x0110,
135 V_Back_Porch = 0x0204,
137 V_Front_Porch = 0x020C,
139 H_Back_Porch = 0x0214,
141 H_Front_Porch = 0x021C,
144 Pixel_Format = 0x0240,
146 Green_Select = 0x0248,
147 Blue_Select = 0x024C,
150 /** Reset value for Bus_Options register */
151 static constexpr size_t BUS_OPTIONS_RESETV = 0x408;
153 /** Reset value for Version register */
154 static constexpr size_t VERSION_RESETV = 0x1CDC0000;
156 /** AXI port width in bytes */
157 static constexpr size_t AXI_PORT_WIDTH = 8;
159 /** max number of beats delivered in one dma burst */
160 static constexpr size_t MAX_BURST_LEN = 16;
162 /** Maximum number of bytes per pixel */
163 static constexpr size_t MAX_PIXEL_SIZE = 4;
166 * @name RegisterFieldLayouts
167 * Bit layout declarations for multi-field registers.
170 BitUnion32(VersionReg)
171 Bitfield<7,0> version_minor;
172 Bitfield<15,8> version_major;
173 Bitfield<31,16> product_id;
174 EndBitUnion(VersionReg)
176 static constexpr uint32_t INT_DMA_END = (1UL << 0);
177 static constexpr uint32_t INT_BUS_ERROR = (1UL << 1);
178 static constexpr uint32_t INT_VSYNC = (1UL << 2);
179 static constexpr uint32_t INT_UNDERRUN = (1UL << 3);
181 BitUnion32(FbLineCountReg)
182 Bitfield<11,0> fb_line_count;
183 Bitfield<31,12> reserved_31_12;
184 EndBitUnion(FbLineCountReg)
186 BitUnion32(BusOptsReg)
187 Bitfield<4,0> burst_len;
188 Bitfield<7,5> reserved_7_5;
189 Bitfield<11,8> max_outstanding;
190 Bitfield<31,12> reserved_31_12;
191 EndBitUnion(BusOptsReg)
193 BitUnion32(TimingReg)
195 Bitfield<31,12> reserved_31_12;
196 EndBitUnion(TimingReg)
198 BitUnion32(PolaritiesReg)
199 Bitfield<0> vsync_polarity;
200 Bitfield<1> hsync_polarity;
201 Bitfield<2> dataen_polarity;
202 Bitfield<3> data_polarity;
203 Bitfield<4> pxlclk_polarity;
204 Bitfield<31,5> reserved_31_5;
205 EndBitUnion(PolaritiesReg)
207 BitUnion32(CommandReg)
209 Bitfield<31,1> reserved_31_1;
210 EndBitUnion(CommandReg)
212 BitUnion32(PixelFormatReg)
213 Bitfield<2,0> reserved_2_0;
214 Bitfield<4,3> bytes_per_pixel;
215 Bitfield<30,5> reserved_30_5;
216 Bitfield<31> big_endian;
217 EndBitUnion(PixelFormatReg)
219 BitUnion32(ColorSelectReg)
220 Bitfield<4,0> offset;
221 Bitfield<7,5> reserved_7_5;
223 Bitfield<15,12> reserved_15_12;
224 Bitfield<23,16> default_color;
225 Bitfield<31,24> reserved_31_24;
226 EndBitUnion(ColorSelectReg)
230 * @name HDLCDRegisters
231 * HDLCD register contents.
234 const VersionReg version; /**< Version register */
235 uint32_t int_rawstat; /**< Interrupt raw status register */
236 uint32_t int_mask; /**< Interrupt mask register */
237 uint32_t fb_base; /**< Frame buffer base address register */
238 uint32_t fb_line_length; /**< Frame buffer Line length register */
239 FbLineCountReg fb_line_count; /**< Frame buffer Line count register */
240 int32_t fb_line_pitch; /**< Frame buffer Line pitch register */
241 BusOptsReg bus_options; /**< Bus options register */
242 TimingReg v_sync; /**< Vertical sync width register */
243 TimingReg v_back_porch; /**< Vertical back porch width register */
244 TimingReg v_data; /**< Vertical data width register */
245 TimingReg v_front_porch; /**< Vertical front porch width register */
246 TimingReg h_sync; /**< Horizontal sync width register */
247 TimingReg h_back_porch; /**< Horizontal back porch width register */
248 TimingReg h_data; /**< Horizontal data width register */
249 TimingReg h_front_porch; /**< Horizontal front porch width reg */
250 PolaritiesReg polarities; /**< Polarities register */
251 CommandReg command; /**< Command register */
252 PixelFormatReg pixel_format; /**< Pixel format register */
253 ColorSelectReg red_select; /**< Red color select register */
254 ColorSelectReg green_select; /**< Green color select register */
255 ColorSelectReg blue_select; /**< Blue color select register */
258 uint32_t readReg(Addr offset);
259 void writeReg(Addr offset, uint32_t value);
261 PixelConverter pixelConverter() const;
262 DisplayTimings displayTimings() const;
264 void createDmaEngine();
269 bool enabled() const { return command.enable; }
271 public: // Pixel pump callbacks
272 bool pxlNext(Pixel &p);
273 void pxlVSyncBegin();
278 protected: // Interrupt handling
280 * Assign new interrupt values and update interrupt signals
282 * A new interrupt is scheduled signalled if the set of unmasked
283 * interrupts goes empty to non-empty. Conversely, if the set of
284 * unmasked interrupts goes from non-empty to empty, the interrupt
287 * @param ints New <i>raw</i> interrupt status
288 * @param mask New interrupt mask
290 void setInterrupts(uint32_t ints, uint32_t mask);
293 * Convenience function to update the interrupt mask
296 * @param mask New interrupt mask
298 void intMask(uint32_t mask) { setInterrupts(int_rawstat, mask); }
301 * Convenience function to raise a new interrupt
304 * @param ints Set of interrupts to raise
306 void intRaise(uint32_t ints) {
307 setInterrupts(int_rawstat | ints, int_mask);
311 * Convenience function to clear interrupts
314 * @param ints Set of interrupts to clear
316 void intClear(uint32_t ints) {
317 setInterrupts(int_rawstat & ~ints, int_mask);
320 /** Masked interrupt status register */
321 uint32_t intStatus() const { return int_rawstat & int_mask; }
323 protected: // Pixel output
324 class PixelPump : public BasePixelPump
327 PixelPump(HDLcd &p, ClockDomain &pxl_clk, unsigned pixel_chunk)
328 : BasePixelPump(p, pxl_clk, pixel_chunk), parent(p) {}
333 bool nextPixel(Pixel &p) override { return parent.pxlNext(p); }
335 void onVSyncBegin() override { return parent.pxlVSyncBegin(); }
336 void onVSyncEnd() override { return parent.pxlVSyncEnd(); }
338 void onUnderrun(unsigned x, unsigned y) override {
339 parent.pxlUnderrun();
342 void onFrameDone() override { parent.pxlFrameDone(); }
348 /** Handler for fast frame refresh in KVM-mode */
350 EventFunctionWrapper virtRefreshEvent;
352 /** Helper to write out bitmaps */
353 std::unique_ptr<ImgWriter> imgWriter;
356 Enums::ImageFormat imgFormat;
358 /** Picture of what the current frame buffer looks like */
361 /** Cached pixel converter, set when the converter is enabled. */
366 protected: // DMA handling
367 class DmaEngine : public DmaReadFifo
370 DmaEngine(HDLcd &_parent, size_t size,
371 unsigned request_size, unsigned max_pending,
372 size_t line_size, ssize_t line_pitch, unsigned num_lines);
374 void startFrame(Addr fb_base);
378 void serialize(CheckpointOut &cp) const override;
379 void unserialize(CheckpointIn &cp) override;
382 void onEndOfBlock() override;
383 void onIdle() override;
386 const size_t lineSize;
387 const ssize_t linePitch;
388 const unsigned numLines;
394 std::unique_ptr<DmaEngine> dmaEngine;
396 protected: // Statistics
398 Stats::Scalar underruns;