Driver for EP93xx LCD controller

Desktop monitor와 embedded LCD 설정

EP93xx LCD controller는 일반 desktop monitor와 embedded LCD display를 모두 구동할 수 있습니다.

Desktop monitor에서는 standard Linux video mode database를 사용할 수 있습니다. Board file의 `struct ep93xxfb_mach_info`에서 `num_modes=EP93XXFB_USE_MODEDB`로 지정하고 예제처럼 `bpp=16`을 설정합니다.

Embedded LCD display에는 `struct fb_videomode` array를 정의해야 합니다. 각 entry에 display 이름과 pixel clock, porch 등의 timing을 채웁니다.

Pixel clock 값은 picosecond 단위이며 `KHZ2PICOS` macro로 변환할 수 있습니다. 대부분의 다른 값은 pixel clock 단위입니다. 자세한 내용은 `Documentation/fb/framebuffer.rst`를 참조합니다.

Embedded mode를 쓸 때 board의 `ep93xxfb_mach_info`는 `num_modes=ARRAY_SIZE(some_board_video_modes)`, `modes=some_board_video_modes`, `default_mode=&some_board_video_modes[0]`, `bpp=16`으로 구성합니다.

Board initialization 함수에서 `ep93xx_register_fb(&some_board_fb_info)`를 호출해 framebuffer device를 등록합니다.

================================
Driver for EP93xx LCD controller
================================

The EP93xx LCD controller can drive both standard desktop monitors and
embedded LCD displays. If you have a standard desktop monitor then you
can use the standard Linux video mode database. In your board file::

        static struct ep93xxfb_mach_info some_board_fb_info = {
                .num_modes        = EP93XXFB_USE_MODEDB,
                .bpp                = 16,
        };

If you have an embedded LCD display then you need to define a video
mode for it as follows::

        static struct fb_videomode some_board_video_modes[] = {
                {
                        .name                = "some_lcd_name",
                        /* Pixel clock, porches, etc */
                },
        };

Note that the pixel clock value is in pico-seconds. You can use the
KHZ2PICOS macro to convert the pixel clock value. Most other values
are in pixel clocks. See Documentation/fb/framebuffer.rst for further
details.

The ep93xxfb_mach_info structure for your board should look like the
following::

        static struct ep93xxfb_mach_info some_board_fb_info = {
                .num_modes        = ARRAY_SIZE(some_board_video_modes),
                .modes                = some_board_video_modes,
                .default_mode        = &some_board_video_modes[0],
                .bpp                = 16,
        };

The framebuffer device can be registered by adding the following to
your board initialisation function::

        ep93xx_register_fb(&some_board_fb_info);

Video attribute와 framebuffer address flag

`ep93xxfb_mach_info.flags`는 controller를 구성하는 데 사용합니다. Video attribute flag의 전체 설명은 EP93xx users' guide section 7에 있습니다.

`EP93XXFB_PCLK_FALLING`은 pixel clock falling edge에서 data를 clock하며 기본은 rising edge입니다. `EP93XXFB_SYNC_BLANK_HIGH`은 blank signal을 active-high로 만들며 기본은 active-low입니다.

`EP93XXFB_SYNC_HORIZ_HIGH`은 horizontal sync를 active-high로 만들며 기본은 active-low입니다. `EP93XXFB_SYNC_VERT_HIGH`은 vertical sync를 active-high로 설정합니다. 원문은 기본 vertical sync도 active-high라고 명시하므로 해당 내용을 그대로 보존합니다.

Framebuffer physical address는 SDCSn 선택 flag로 제어합니다. `EP93XXFB_USE_SDCSN0`이 기본이고, `EP93XXFB_USE_SDCSN1`, `EP93XXFB_USE_SDCSN2`, `EP93XXFB_USE_SDCSN3`으로 각각 다른 chip-select 영역을 선택할 수 있습니다.

Video Attribute Flags
=====================

The ep93xxfb_mach_info structure has a flags field which can be used
to configure the controller. The video attributes flags are fully
documented in section 7 of the EP93xx users' guide. The following
flags are available:

=============================== ==========================================
EP93XXFB_PCLK_FALLING                Clock data on the falling edge of the
                                pixel clock. The default is to clock
                                data on the rising edge.

EP93XXFB_SYNC_BLANK_HIGH        Blank signal is active high. By
                                default the blank signal is active low.

EP93XXFB_SYNC_HORIZ_HIGH        Horizontal sync is active high. By
                                default the horizontal sync is active low.

EP93XXFB_SYNC_VERT_HIGH                Vertical sync is active high. By
                                default the vertical sync is active high.
=============================== ==========================================

The physical address of the framebuffer can be controlled using the
following flags:

=============================== ======================================
EP93XXFB_USE_SDCSN0                Use SDCSn[0] for the framebuffer. This
                                is the default setting.

EP93XXFB_USE_SDCSN1                Use SDCSn[1] for the framebuffer.

EP93XXFB_USE_SDCSN2                Use SDCSn[2] for the framebuffer.

EP93XXFB_USE_SDCSN3                Use SDCSn[3] for the framebuffer.
=============================== ======================================

Optional platform callback

EP93xx framebuffer driver는 `setup`, `teardown`, `blank` 세 optional platform callback을 지원합니다.

`setup`은 framebuffer driver가 설치될 때, `teardown`은 제거될 때 호출됩니다. `blank`는 display가 blank 또는 unblank될 때마다 호출됩니다.

Setup과 teardown 함수는 `struct platform_device`를 argument로 받습니다. `pdev->dev.platform_data`에서 `struct ep93xxfb_mach_info`를 얻고 `platform_get_drvdata(pdev)`에서 `struct fb_info`를 얻을 수 있습니다. 이후 callback에서 board-specific framebuffer setup을 수행합니다.

Platform callbacks
==================

The EP93xx framebuffer driver supports three optional platform
callbacks: setup, teardown and blank. The setup and teardown functions
are called when the framebuffer driver is installed and removed
respectively. The blank function is called whenever the display is
blanked or unblanked.

The setup and teardown devices pass the platform_device structure as
an argument. The fb_info and ep93xxfb_mach_info structures can be
obtained as follows::

        static int some_board_fb_setup(struct platform_device *pdev)
        {
                struct ep93xxfb_mach_info *mach_info = pdev->dev.platform_data;
                struct fb_info *fb_info = platform_get_drvdata(pdev);

                /* Board specific framebuffer setup */
        }

Kernel command line과 module mode 설정

Video mode 문자열 형식은 `video=XRESxYRES[-BPP][@REFRESH]`입니다. Resolution은 필수이고 bits per pixel과 refresh rate는 선택 항목입니다.

EP93xx video driver가 built-in이면 Linux kernel command line에서 mode를 설정합니다. 예제 `video=ep93xx-fb:800x600-16@60`은 800x600, 16 bpp, 60 Hz를 선택합니다.

Driver가 module이면 설치 시 `modprobe ep93xx-fb video=320x240`처럼 `video` parameter를 전달합니다.

Setting the video mode
======================

The video mode is set using the following syntax::

        video=XRESxYRES[-BPP][@REFRESH]

If the EP93xx video driver is built-in then the video mode is set on
the Linux kernel command line, for example::

        video=ep93xx-fb:800x600-16@60

If the EP93xx video driver is built as a module then the video mode is
set when the module is installed::

        modprobe ep93xx-fb video=320x240

EP9315 VIDSCRNPAGE bit 27 silicon bug

적어도 EP9315에는 framebuffer physical offset register인 `VIDSCRNPAGE`의 bit 27이 low에 고정되는 silicon bug가 있습니다. 문서는 관련 unofficial errata URL을 제공합니다.

기본적으로 EP93xx framebuffer driver는 할당된 physical address의 bit 27이 설정돼 있는지 검사합니다. 설정돼 있으면 memory를 해제하고 오류를 반환해 사용할 수 없는 framebuffer address를 거부합니다.

Driver를 load할 때 `ep93xx-fb.check_screenpage_bug=0`을 지정하면 이 검사를 비활성화할 수 있습니다.

일부 system에서는 SDRAM layout을 재구성해 bug를 피할 수 있습니다. 자세한 내용은 EP93xx users' guide section 13을 참조합니다.

Screenpage bug
==============

At least on the EP9315 there is a silicon bug which causes bit 27 of
the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
an unofficial errata for this bug at::

        https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2

By default the EP93xx framebuffer driver checks if the allocated physical
address has bit 27 set. If it does, then the memory is freed and an
error is returned. The check can be disabled by adding the following
option when loading the driver::

      ep93xx-fb.check_screenpage_bug=0

In some cases it may be possible to reconfigure your SDRAM layout to
avoid this bug. See section 13 of the EP93xx users' guide for details.