From ab42b818954c040fa13639dc031d8541edcecb4b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:45 -0300 Subject: [PATCH] docs: fb: convert docs to ReST and rename to *.rst The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Also, removed the Maintained by, as requested by Geert. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- .../admin-guide/kernel-parameters.txt | 2 +- Documentation/fb/{api.txt => api.rst} | 29 +- Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +- .../fb/{aty128fb.txt => aty128fb.rst} | 35 +- .../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +- .../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +-- .../fb/{deferred_io.txt => deferred_io.rst} | 28 +- Documentation/fb/{efifb.txt => efifb.rst} | 18 +- .../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +- Documentation/fb/{fbcon.txt => fbcon.rst} | 179 +++---- .../fb/{framebuffer.txt => framebuffer.rst} | 80 ++-- Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +- Documentation/fb/index.rst | 50 ++ .../fb/{intel810.txt => intel810.rst} | 79 ++-- Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +-- .../fb/{internals.txt => internals.rst} | 24 +- Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +- Documentation/fb/matroxfb.rst | 443 ++++++++++++++++++ Documentation/fb/matroxfb.txt | 413 ---------------- .../fb/{metronomefb.txt => metronomefb.rst} | 8 +- Documentation/fb/{modedb.txt => modedb.rst} | 44 +- Documentation/fb/pvr2fb.rst | 66 +++ Documentation/fb/pvr2fb.txt | 65 --- Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +++- Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +- .../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +- Documentation/fb/sh7760fb.rst | 130 +++++ Documentation/fb/sh7760fb.txt | 131 ------ Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +- Documentation/fb/{sm501.txt => sm501.rst} | 7 +- Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +- Documentation/fb/sstfb.rst | 207 ++++++++ Documentation/fb/sstfb.txt | 174 ------- Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +- .../fb/{tridentfb.txt => tridentfb.rst} | 36 +- Documentation/fb/{udlfb.txt => udlfb.rst} | 55 ++- Documentation/fb/{uvesafb.txt => uvesafb.rst} | 142 +++--- Documentation/fb/{vesafb.txt => vesafb.rst} | 121 ++--- Documentation/fb/viafb.rst | 297 ++++++++++++ Documentation/fb/viafb.txt | 252 ---------- .../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +- MAINTAINERS | 10 +- drivers/tty/Kconfig | 2 +- drivers/video/fbdev/Kconfig | 24 +- drivers/video/fbdev/matrox/matroxfb_base.c | 2 +- drivers/video/fbdev/pxafb.c | 2 +- drivers/video/fbdev/sh7760fb.c | 2 +- 47 files changed, 1952 insertions(+), 1665 deletions(-) rename Documentation/fb/{api.txt => api.rst} (97%) rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%) rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%) rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%) rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%) rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%) rename Documentation/fb/{efifb.txt => efifb.rst} (75%) rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%) rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%) rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%) rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%) create mode 100644 Documentation/fb/index.rst rename Documentation/fb/{intel810.txt => intel810.rst} (83%) rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%) rename Documentation/fb/{internals.txt => internals.rst} (82%) rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%) create mode 100644 Documentation/fb/matroxfb.rst delete mode 100644 Documentation/fb/matroxfb.txt rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%) rename Documentation/fb/{modedb.txt => modedb.rst} (87%) create mode 100644 Documentation/fb/pvr2fb.rst delete mode 100644 Documentation/fb/pvr2fb.txt rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%) rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%) rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%) create mode 100644 Documentation/fb/sh7760fb.rst delete mode 100644 Documentation/fb/sh7760fb.txt rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%) rename Documentation/fb/{sm501.txt => sm501.rst} (65%) rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%) create mode 100644 Documentation/fb/sstfb.rst delete mode 100644 Documentation/fb/sstfb.txt rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%) rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%) rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%) rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%) rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%) create mode 100644 Documentation/fb/viafb.rst delete mode 100644 Documentation/fb/viafb.txt rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 9b16b640ce48..83d6560f10f0 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -5024,7 +5024,7 @@ vector=percpu: enable percpu vector domain video= [FB] Frame buffer configuration - See Documentation/fb/modedb.txt. + See Documentation/fb/modedb.rst. video.brightness_switch_enabled= [0,1] If set to 1, on receiving an ACPI notify event diff --git a/Documentation/fb/api.txt b/Documentation/fb/api.rst similarity index 97% rename from Documentation/fb/api.txt rename to Documentation/fb/api.rst index d52cf1e3b975..79ec33dded74 100644 --- a/Documentation/fb/api.txt +++ b/Documentation/fb/api.rst @@ -1,5 +1,6 @@ - The Frame Buffer Device API - --------------------------- +=========================== +The Frame Buffer Device API +=========================== Last revised: June 21, 2011 @@ -21,13 +22,13 @@ deal with different behaviours. --------------- Device and driver capabilities are reported in the fixed screen information -capabilities field. +capabilities field:: -struct fb_fix_screeninfo { + struct fb_fix_screeninfo { ... __u16 capabilities; /* see FB_CAP_* */ ... -}; + }; Application should use those capabilities to find out what features they can expect from the device and driver. @@ -151,9 +152,9 @@ fb_fix_screeninfo and fb_var_screeninfo structure respectively. struct fb_fix_screeninfo stores device independent unchangeable information about the frame buffer device and the current format. Those information can't be directly modified by applications, but can be changed by the driver when an -application modifies the format. +application modifies the format:: -struct fb_fix_screeninfo { + struct fb_fix_screeninfo { char id[16]; /* identification string eg "TT Builtin" */ unsigned long smem_start; /* Start of frame buffer mem */ /* (physical address) */ @@ -172,13 +173,13 @@ struct fb_fix_screeninfo { /* specific chip/card we have */ __u16 capabilities; /* see FB_CAP_* */ __u16 reserved[2]; /* Reserved for future compatibility */ -}; + }; struct fb_var_screeninfo stores device independent changeable information about a frame buffer device, its current format and video mode, as well as -other miscellaneous parameters. +other miscellaneous parameters:: -struct fb_var_screeninfo { + struct fb_var_screeninfo { __u32 xres; /* visible resolution */ __u32 yres; __u32 xres_virtual; /* virtual resolution */ @@ -216,7 +217,7 @@ struct fb_var_screeninfo { __u32 rotate; /* angle we rotate counter clockwise */ __u32 colorspace; /* colorspace for FOURCC-based modes */ __u32 reserved[4]; /* Reserved for future compatibility */ -}; + }; To modify variable information, applications call the FBIOPUT_VSCREENINFO ioctl with a pointer to a fb_var_screeninfo structure. If the call is @@ -255,14 +256,14 @@ monochrome, grayscale or pseudocolor visuals, although this is not required. - For truecolor and directcolor formats, applications set the grayscale field to zero, and the red, blue, green and transp fields to describe the layout of - color components in memory. + color components in memory:: -struct fb_bitfield { + struct fb_bitfield { __u32 offset; /* beginning of bitfield */ __u32 length; /* length of bitfield */ __u32 msb_right; /* != 0 : Most significant bit is */ /* right */ -}; + }; Pixel values are bits_per_pixel wide and are split in non-overlapping red, green, blue and alpha (transparency) components. Location and size of each diff --git a/Documentation/fb/arkfb.txt b/Documentation/fb/arkfb.rst similarity index 92% rename from Documentation/fb/arkfb.txt rename to Documentation/fb/arkfb.rst index e8487a9d6a05..aeca8773dd7e 100644 --- a/Documentation/fb/arkfb.txt +++ b/Documentation/fb/arkfb.rst @@ -1,6 +1,6 @@ - - arkfb - fbdev driver for ARK Logic chips - ======================================== +======================================== +arkfb - fbdev driver for ARK Logic chips +======================================== Supported Hardware @@ -47,7 +47,7 @@ Missing Features (alias TODO list) * secondary (not initialized by BIOS) device support - * big endian support + * big endian support * DPMS support * MMIO support * interlaced mode variant diff --git a/Documentation/fb/aty128fb.txt b/Documentation/fb/aty128fb.rst similarity index 61% rename from Documentation/fb/aty128fb.txt rename to Documentation/fb/aty128fb.rst index b605204fcfe1..3f107718f933 100644 --- a/Documentation/fb/aty128fb.txt +++ b/Documentation/fb/aty128fb.rst @@ -1,8 +1,9 @@ -[This file is cloned from VesaFB/matroxfb] - +================= What is aty128fb? ================= +.. [This file is cloned from VesaFB/matroxfb] + This is a driver for a graphic framebuffer for ATI Rage128 based devices on Intel and PPC boxes. @@ -24,15 +25,15 @@ How to use it? ============== Switching modes is done using the video=aty128fb:... modedb -boot parameter or using `fbset' program. +boot parameter or using `fbset` program. -See Documentation/fb/modedb.txt for more information on modedb +See Documentation/fb/modedb.rst for more information on modedb resolutions. You should compile in both vgacon (to boot if you remove your Rage128 from box) and aty128fb (for graphics mode). You should not compile-in vesafb -unless you have primary display on non-Rage128 VBE2.0 device (see -Documentation/fb/vesafb.txt for details). +unless you have primary display on non-Rage128 VBE2.0 device (see +Documentation/fb/vesafb.rst for details). X11 @@ -48,16 +49,18 @@ Configuration ============= You can pass kernel command line options to vesafb with -`video=aty128fb:option1,option2:value2,option3' (multiple options should -be separated by comma, values are separated from options by `:'). +`video=aty128fb:option1,option2:value2,option3` (multiple options should +be separated by comma, values are separated from options by `:`). Accepted options: -noaccel - do not use acceleration engine. It is default. -accel - use acceleration engine. Not finished. -vmode:x - chooses PowerMacintosh video mode . Deprecated. -cmode:x - chooses PowerMacintosh colour mode . Deprecated. - - selects startup videomode. See modedb.txt for detailed - explanation. Default is 640x480x8bpp. +========= ======================================================= +noaccel do not use acceleration engine. It is default. +accel use acceleration engine. Not finished. +vmode:x chooses PowerMacintosh video mode . Deprecated. +cmode:x chooses PowerMacintosh colour mode . Deprecated. + selects startup videomode. See modedb.txt for detailed + explanation. Default is 640x480x8bpp. +========= ======================================================= Limitations @@ -65,8 +68,8 @@ Limitations There are known and unknown bugs, features and misfeatures. Currently there are following known bugs: - + This driver is still experimental and is not finished. Too many + + - This driver is still experimental and is not finished. Too many bugs/errata to list here. --- Brad Douglas diff --git a/Documentation/fb/cirrusfb.txt b/Documentation/fb/cirrusfb.rst similarity index 75% rename from Documentation/fb/cirrusfb.txt rename to Documentation/fb/cirrusfb.rst index f75950d330a4..8c3e6c6cb114 100644 --- a/Documentation/fb/cirrusfb.txt +++ b/Documentation/fb/cirrusfb.rst @@ -1,32 +1,32 @@ +============================================ +Framebuffer driver for Cirrus Logic chipsets +============================================ - Framebuffer driver for Cirrus Logic chipsets - Copyright 1999 Jeff Garzik +Copyright 1999 Jeff Garzik - -{ just a little something to get people going; contributors welcome! } - +.. just a little something to get people going; contributors welcome! Chip families supported: - SD64 - Piccolo - Picasso - Spectrum - Alpine (GD-543x/4x) - Picasso4 (GD-5446) - GD-5480 - Laguna (GD-546x) + - SD64 + - Piccolo + - Picasso + - Spectrum + - Alpine (GD-543x/4x) + - Picasso4 (GD-5446) + - GD-5480 + - Laguna (GD-546x) Bus's supported: - PCI - Zorro + - PCI + - Zorro Architectures supported: - i386 - Alpha - PPC (Motorola Powerstack) - m68k (Amiga) + - i386 + - Alpha + - PPC (Motorola Powerstack) + - m68k (Amiga) @@ -34,10 +34,9 @@ Default video modes ------------------- At the moment, there are two kernel command line arguments supported: -mode:640x480 -mode:800x600 - or -mode:1024x768 +- mode:640x480 +- mode:800x600 +- mode:1024x768 Full support for startup video modes (modedb) will be integrated soon. @@ -93,5 +92,3 @@ Version 1.9.4 Version 1.9.3 ------------- * Bundled with kernel 2.3.14-pre1 or later. - - diff --git a/Documentation/fb/cmap_xfbdev.txt b/Documentation/fb/cmap_xfbdev.rst similarity index 50% rename from Documentation/fb/cmap_xfbdev.txt rename to Documentation/fb/cmap_xfbdev.rst index 55e1f0a3d2b4..5db5e9787361 100644 --- a/Documentation/fb/cmap_xfbdev.txt +++ b/Documentation/fb/cmap_xfbdev.rst @@ -1,26 +1,29 @@ +========================== Understanding fbdev's cmap --------------------------- +========================== These notes explain how X's dix layer uses fbdev's cmap structures. -*. example of relevant structures in fbdev as used for a 3-bit grayscale cmap -struct fb_var_screeninfo { - .bits_per_pixel = 8, - .grayscale = 1, - .red = { 4, 3, 0 }, - .green = { 0, 0, 0 }, - .blue = { 0, 0, 0 }, -} -struct fb_fix_screeninfo { - .visual = FB_VISUAL_STATIC_PSEUDOCOLOR, -} -for (i = 0; i < 8; i++) +- example of relevant structures in fbdev as used for a 3-bit grayscale cmap:: + + struct fb_var_screeninfo { + .bits_per_pixel = 8, + .grayscale = 1, + .red = { 4, 3, 0 }, + .green = { 0, 0, 0 }, + .blue = { 0, 0, 0 }, + } + struct fb_fix_screeninfo { + .visual = FB_VISUAL_STATIC_PSEUDOCOLOR, + } + for (i = 0; i < 8; i++) info->cmap.red[i] = (((2*i)+1)*(0xFFFF))/16; -memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8); -memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8); + memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8); + memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8); -*. X11 apps do something like the following when trying to use grayscale. -for (i=0; i < 8; i++) { +- X11 apps do something like the following when trying to use grayscale:: + + for (i=0; i < 8; i++) { char colorspec[64]; memset(colorspec,0,64); sprintf(colorspec, "rgb:%x/%x/%x", i*36,i*36,i*36); @@ -28,26 +31,26 @@ for (i=0; i < 8; i++) { printf("Can't get color %s\n",colorspec); XAllocColor(outputDisplay, testColormap, &wantedColor); grays[i] = wantedColor; -} + } + There's also named equivalents like gray1..x provided you have an rgb.txt. Somewhere in X's callchain, this results in a call to X code that handles the colormap. For example, Xfbdev hits the following: -xc-011010/programs/Xserver/dix/colormap.c: +xc-011010/programs/Xserver/dix/colormap.c:: -FindBestPixel(pentFirst, size, prgb, channel) + FindBestPixel(pentFirst, size, prgb, channel) -dr = (long) pent->co.local.red - prgb->red; -dg = (long) pent->co.local.green - prgb->green; -db = (long) pent->co.local.blue - prgb->blue; -sq = dr * dr; -UnsignedToBigNum (sq, &sum); -BigNumAdd (&sum, &temp, &sum); + dr = (long) pent->co.local.red - prgb->red; + dg = (long) pent->co.local.green - prgb->green; + db = (long) pent->co.local.blue - prgb->blue; + sq = dr * dr; + UnsignedToBigNum (sq, &sum); + BigNumAdd (&sum, &temp, &sum); co.local.red are entries that were brought in through FBIOGETCMAP which come directly from the info->cmap.red that was listed above. The prgb is the rgb that the app wants to match to. The above code is doing what looks like a least squares matching function. That's why the cmap entries can't be set to the left hand side boundaries of a color range. - diff --git a/Documentation/fb/deferred_io.txt b/Documentation/fb/deferred_io.rst similarity index 86% rename from Documentation/fb/deferred_io.txt rename to Documentation/fb/deferred_io.rst index 748328370250..7300cff255a3 100644 --- a/Documentation/fb/deferred_io.txt +++ b/Documentation/fb/deferred_io.rst @@ -1,5 +1,6 @@ +=========== Deferred IO ------------ +=========== Deferred IO is a way to delay and repurpose IO. It uses host memory as a buffer and the MMU pagefault as a pretrigger for when to perform the device @@ -16,7 +17,7 @@ works: - app continues writing to that page with no additional cost. this is the key benefit. - the workqueue task comes in and mkcleans the pages on the list, then - completes the work associated with updating the framebuffer. this is + completes the work associated with updating the framebuffer. this is the real work talking to the device. - app tries to write to the address (that has now been mkcleaned) - get pagefault and the above sequence occurs again @@ -47,29 +48,32 @@ How to use it: (for fbdev drivers) ---------------------------------- The following example may be helpful. -1. Setup your structure. Eg: +1. Setup your structure. Eg:: -static struct fb_deferred_io hecubafb_defio = { - .delay = HZ, - .deferred_io = hecubafb_dpy_deferred_io, -}; + static struct fb_deferred_io hecubafb_defio = { + .delay = HZ, + .deferred_io = hecubafb_dpy_deferred_io, + }; The delay is the minimum delay between when the page_mkwrite trigger occurs and when the deferred_io callback is called. The deferred_io callback is explained below. -2. Setup your deferred IO callback. Eg: -static void hecubafb_dpy_deferred_io(struct fb_info *info, - struct list_head *pagelist) +2. Setup your deferred IO callback. Eg:: + + static void hecubafb_dpy_deferred_io(struct fb_info *info, + struct list_head *pagelist) The deferred_io callback is where you would perform all your IO to the display device. You receive the pagelist which is the list of pages that were written to during the delay. You must not modify this list. This callback is called from a workqueue. -3. Call init +3. Call init:: + info->fbdefio = &hecubafb_defio; fb_deferred_io_init(info); -4. Call cleanup +4. Call cleanup:: + fb_deferred_io_cleanup(info); diff --git a/Documentation/fb/efifb.txt b/Documentation/fb/efifb.rst similarity index 75% rename from Documentation/fb/efifb.txt rename to Documentation/fb/efifb.rst index 1a85c1bdaf38..04840331a00e 100644 --- a/Documentation/fb/efifb.txt +++ b/Documentation/fb/efifb.rst @@ -1,6 +1,6 @@ - +============== What is efifb? -=============== +============== This is a generic EFI platform driver for Intel based Apple computers. efifb is only for EFI booted Intel Macs. @@ -8,16 +8,17 @@ efifb is only for EFI booted Intel Macs. Supported Hardware ================== -iMac 17"/20" -Macbook -Macbook Pro 15"/17" -MacMini +- iMac 17"/20" +- Macbook +- Macbook Pro 15"/17" +- MacMini How to use it? ============== efifb does not have any kind of autodetection of your machine. -You have to add the following kernel parameters in your elilo.conf: +You have to add the following kernel parameters in your elilo.conf:: + Macbook : video=efifb:macbook MacMini : @@ -29,9 +30,10 @@ You have to add the following kernel parameters in your elilo.conf: Accepted options: +======= =========================================================== nowc Don't map the framebuffer write combined. This can be used to workaround side-effects and slowdowns on other CPU cores when large amounts of console data are written. +======= =========================================================== --- Edgar Hucek diff --git a/Documentation/fb/ep93xx-fb.txt b/Documentation/fb/ep93xx-fb.rst similarity index 85% rename from Documentation/fb/ep93xx-fb.txt rename to Documentation/fb/ep93xx-fb.rst index 5af1bd9effae..6f7767926d1a 100644 --- a/Documentation/fb/ep93xx-fb.txt +++ b/Documentation/fb/ep93xx-fb.rst @@ -4,7 +4,7 @@ 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: +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, @@ -12,7 +12,7 @@ can use the standard Linux video mode database. In your board file: }; If you have an embedded LCD display then you need to define a video -mode for it as follows: +mode for it as follows:: static struct fb_videomode some_board_video_modes[] = { { @@ -23,11 +23,11 @@ mode for it as follows: 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.txt for further +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: +following:: static struct ep93xxfb_mach_info some_board_fb_info = { .num_modes = ARRAY_SIZE(some_board_video_modes), @@ -37,7 +37,7 @@ following: }; The framebuffer device can be registered by adding the following to -your board initialisation function: +your board initialisation function:: ep93xx_register_fb(&some_board_fb_info); @@ -50,6 +50,7 @@ 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. @@ -62,10 +63,12 @@ EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By 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. @@ -74,6 +77,7 @@ 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. +=============================== ====================================== ================== Platform callbacks @@ -87,7 +91,7 @@ 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: +obtained as follows:: static int some_board_fb_setup(struct platform_device *pdev) { @@ -101,17 +105,17 @@ obtained as follows: Setting the video mode ====================== -The video mode is set using the following syntax: +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: +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: +set when the module is installed:: modprobe ep93xx-fb video=320x240 @@ -121,13 +125,14 @@ 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: +an unofficial errata for this bug at:: + http://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: +option when loading the driver:: ep93xx-fb.check_screenpage_bug=0 diff --git a/Documentation/fb/fbcon.txt b/Documentation/fb/fbcon.rst similarity index 69% rename from Documentation/fb/fbcon.txt rename to Documentation/fb/fbcon.rst index 60a5ec04e8f0..cfb9f7c38f18 100644 --- a/Documentation/fb/fbcon.txt +++ b/Documentation/fb/fbcon.rst @@ -1,39 +1,41 @@ +======================= The Framebuffer Console ======================= - The framebuffer console (fbcon), as its name implies, is a text +The framebuffer console (fbcon), as its name implies, is a text console running on top of the framebuffer device. It has the functionality of any standard text console driver, such as the VGA console, with the added features that can be attributed to the graphical nature of the framebuffer. - In the x86 architecture, the framebuffer console is optional, and +In the x86 architecture, the framebuffer console is optional, and some even treat it as a toy. For other architectures, it is the only available display device, text or graphical. - What are the features of fbcon? The framebuffer console supports +What are the features of fbcon? The framebuffer console supports high resolutions, varying font types, display rotation, primitive multihead, etc. Theoretically, multi-colored fonts, blending, aliasing, and any feature made available by the underlying graphics card are also possible. A. Configuration +================ - The framebuffer console can be enabled by using your favorite kernel +The framebuffer console can be enabled by using your favorite kernel configuration tool. It is under Device Drivers->Graphics Support->Frame buffer Devices->Console display driver support->Framebuffer Console Support. Select 'y' to compile support statically or 'm' for module support. The module will be fbcon. - In order for fbcon to activate, at least one framebuffer driver is +In order for fbcon to activate, at least one framebuffer driver is required, so choose from any of the numerous drivers available. For x86 systems, they almost universally have VGA cards, so vga16fb and vesafb will always be available. However, using a chipset-specific driver will give you more speed and features, such as the ability to change the video mode dynamically. - To display the penguin logo, choose any logo available in Graphics +To display the penguin logo, choose any logo available in Graphics support->Bootup logo. - Also, you will need to select at least one compiled-in font, but if +Also, you will need to select at least one compiled-in font, but if you don't do anything, the kernel configuration tool will select one for you, usually an 8x16 font. @@ -44,6 +46,7 @@ fortunate to have a driver that does not alter the graphics chip, then you will still get a VGA console. B. Loading +========== Possible scenarios: @@ -72,33 +75,33 @@ Possible scenarios: C. Boot options - The framebuffer console has several, largely unknown, boot options - that can change its behavior. + The framebuffer console has several, largely unknown, boot options + that can change its behavior. 1. fbcon=font: - Select the initial font to use. The value 'name' can be any of the - compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6, - PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8. + Select the initial font to use. The value 'name' can be any of the + compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6, + PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8. Note, not all drivers can handle font with widths not divisible by 8, - such as vga16fb. + such as vga16fb. 2. fbcon=scrollback:[k] - The scrollback buffer is memory that is used to preserve display - contents that has already scrolled past your view. This is accessed - by using the Shift-PageUp key combination. The value 'value' is any - integer. It defaults to 32KB. The 'k' suffix is optional, and will - multiply the 'value' by 1024. + The scrollback buffer is memory that is used to preserve display + contents that has already scrolled past your view. This is accessed + by using the Shift-PageUp key combination. The value 'value' is any + integer. It defaults to 32KB. The 'k' suffix is optional, and will + multiply the 'value' by 1024. 3. fbcon=map:<0123> - This is an interesting option. It tells which driver gets mapped to - which console. The value '0123' is a sequence that gets repeated until - the total length is 64 which is the number of consoles available. In - the above example, it is expanded to 012301230123... and the mapping - will be: + This is an interesting option. It tells which driver gets mapped to + which console. The value '0123' is a sequence that gets repeated until + the total length is 64 which is the number of consoles available. In + the above example, it is expanded to 012301230123... and the mapping + will be:: tty | 1 2 3 4 5 6 7 8 9 ... fb | 0 1 2 3 0 1 2 3 0 ... @@ -126,20 +129,20 @@ C. Boot options 4. fbcon=rotate: - This option changes the orientation angle of the console display. The - value 'n' accepts the following: + This option changes the orientation angle of the console display. The + value 'n' accepts the following: - 0 - normal orientation (0 degree) - 1 - clockwise orientation (90 degrees) - 2 - upside down orientation (180 degrees) - 3 - counterclockwise orientation (270 degrees) + - 0 - normal orientation (0 degree) + - 1 - clockwise orientation (90 degrees) + - 2 - upside down orientation (180 degrees) + - 3 - counterclockwise orientation (270 degrees) The angle can be changed anytime afterwards by 'echoing' the same numbers to any one of the 2 attributes found in /sys/class/graphics/fbcon: - rotate - rotate the display of the active console - rotate_all - rotate the display of all consoles + - rotate - rotate the display of the active console + - rotate_all - rotate the display of all consoles Console rotation will only become available if Framebuffer Console Rotation support is compiled in your kernel. @@ -177,9 +180,9 @@ Before going on to how to attach, detach and unload the framebuffer console, an illustration of the dependencies may help. The console layer, as with most subsystems, needs a driver that interfaces with -the hardware. Thus, in a VGA console: +the hardware. Thus, in a VGA console:: -console ---> VGA driver ---> hardware. + console ---> VGA driver ---> hardware. Assuming the VGA driver can be unloaded, one must first unbind the VGA driver from the console layer before unloading the driver. The VGA driver cannot be @@ -187,9 +190,9 @@ unloaded if it is still bound to the console layer. (See Documentation/console/console.txt for more information). This is more complicated in the case of the framebuffer console (fbcon), -because fbcon is an intermediate layer between the console and the drivers: +because fbcon is an intermediate layer between the console and the drivers:: -console ---> fbcon ---> fbdev drivers ---> hardware + console ---> fbcon ---> fbdev drivers ---> hardware The fbdev drivers cannot be unloaded if bound to fbcon, and fbcon cannot be unloaded if it's bound to the console layer. @@ -204,12 +207,12 @@ So, how do we unbind fbcon from the console? Part of the answer is in Documentation/console/console.txt. To summarize: Echo a value to the bind file that represents the framebuffer console -driver. So assuming vtcon1 represents fbcon, then: +driver. So assuming vtcon1 represents fbcon, then:: -echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to - console layer -echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from - console layer + echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to + console layer + echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from + console layer If fbcon is detached from the console layer, your boot console driver (which is usually VGA text mode) will take over. A few drivers (rivafb and i810fb) will @@ -223,19 +226,19 @@ restored properly. The following is one of the several methods that you can do: 2. In your kernel configuration, ensure that CONFIG_FRAMEBUFFER_CONSOLE is set to 'y' or 'm'. Enable one or more of your favorite framebuffer drivers. -3. Boot into text mode and as root run: +3. Boot into text mode and as root run:: vbetool vbestate save > - The above command saves the register contents of your graphics - hardware to . You need to do this step only once as - the state file can be reused. + The above command saves the register contents of your graphics + hardware to . You need to do this step only once as + the state file can be reused. -4. If fbcon is compiled as a module, load fbcon by doing: +4. If fbcon is compiled as a module, load fbcon by doing:: modprobe fbcon -5. Now to detach fbcon: +5. Now to detach fbcon:: vbetool vbestate restore < && \ echo 0 > /sys/class/vtconsole/vtcon1/bind @@ -243,7 +246,7 @@ restored properly. The following is one of the several methods that you can do: 6. That's it, you're back to VGA mode. And if you compiled fbcon as a module, you can unload it by 'rmmod fbcon'. -7. To reattach fbcon: +7. To reattach fbcon:: echo 1 > /sys/class/vtconsole/vtcon1/bind @@ -266,82 +269,82 @@ the following: Variation 1: - a. Before detaching fbcon, do + a. Before detaching fbcon, do:: - vbetool vbemode save > # do once for each vesafb mode, - # the file can be reused + vbetool vbemode save > # do once for each vesafb mode, + # the file can be reused b. Detach fbcon as in step 5. - c. Attach fbcon + c. Attach fbcon:: - vbetool vbestate restore < && \ + vbetool vbestate restore < && \ echo 1 > /sys/class/vtconsole/vtcon1/bind Variation 2: - a. Before detaching fbcon, do: - echo > /sys/class/tty/console/bind + a. Before detaching fbcon, do:: + echo > /sys/class/tty/console/bind - vbetool vbemode get + vbetool vbemode get b. Take note of the mode number b. Detach fbcon as in step 5. - c. Attach fbcon: + c. Attach fbcon:: - vbetool vbemode set && \ - echo 1 > /sys/class/vtconsole/vtcon1/bind + vbetool vbemode set && \ + echo 1 > /sys/class/vtconsole/vtcon1/bind Samples: ======== Here are 2 sample bash scripts that you can use to bind or unbind the -framebuffer console driver if you are on an X86 box: +framebuffer console driver if you are on an X86 box:: ---------------------------------------------------------------------------- -#!/bin/bash -# Unbind fbcon + #!/bin/bash + # Unbind fbcon -# Change this to where your actual vgastate file is located -# Or Use VGASTATE=$1 to indicate the state file at runtime -VGASTATE=/tmp/vgastate + # Change this to where your actual vgastate file is located + # Or Use VGASTATE=$1 to indicate the state file at runtime + VGASTATE=/tmp/vgastate -# path to vbetool -VBETOOL=/usr/local/bin + # path to vbetool + VBETOOL=/usr/local/bin -for (( i = 0; i < 16; i++)) -do - if test -x /sys/class/vtconsole/vtcon$i; then - if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \ - = 1 ]; then + for (( i = 0; i < 16; i++)) + do + if test -x /sys/class/vtconsole/vtcon$i; then + if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \ + = 1 ]; then if test -x $VBETOOL/vbetool; then echo Unbinding vtcon$i $VBETOOL/vbetool vbestate restore < $VGASTATE echo 0 > /sys/class/vtconsole/vtcon$i/bind fi - fi - fi -done + fi + fi + done --------------------------------------------------------------------------- -#!/bin/bash -# Bind fbcon - -for (( i = 0; i < 16; i++)) -do - if test -x /sys/class/vtconsole/vtcon$i; then - if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \ - = 1 ]; then + +:: + + #!/bin/bash + # Bind fbcon + + for (( i = 0; i < 16; i++)) + do + if test -x /sys/class/vtconsole/vtcon$i; then + if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \ + = 1 ]; then echo Unbinding vtcon$i echo 1 > /sys/class/vtconsole/vtcon$i/bind - fi - fi -done ---------------------------------------------------------------------------- + fi + fi + done --- Antonino Daplas diff --git a/Documentation/fb/framebuffer.txt b/Documentation/fb/framebuffer.rst similarity index 92% rename from Documentation/fb/framebuffer.txt rename to Documentation/fb/framebuffer.rst index 58c5ae2e9f59..7fe087310c82 100644 --- a/Documentation/fb/framebuffer.txt +++ b/Documentation/fb/framebuffer.rst @@ -1,7 +1,7 @@ - The Frame Buffer Device - ----------------------- +======================= +The Frame Buffer Device +======================= -Maintained by Geert Uytterhoeven Last revised: May 10, 2001 @@ -26,7 +26,7 @@ other device in /dev. It's a character device using major 29; the minor specifies the frame buffer number. By convention, the following device nodes are used (numbers indicate the device -minor numbers): +minor numbers):: 0 = /dev/fb0 First frame buffer 1 = /dev/fb1 Second frame buffer @@ -34,15 +34,15 @@ minor numbers): 31 = /dev/fb31 32nd frame buffer For backwards compatibility, you may want to create the following symbolic -links: +links:: /dev/fb0current -> fb0 /dev/fb1current -> fb1 and so on... -The frame buffer devices are also `normal' memory devices, this means, you can -read and write their contents. You can, for example, make a screen snapshot by +The frame buffer devices are also `normal` memory devices, this means, you can +read and write their contents. You can, for example, make a screen snapshot by:: cp /dev/fb0 myfile @@ -54,11 +54,11 @@ Application software that uses the frame buffer device (e.g. the X server) will use /dev/fb0 by default (older software uses /dev/fb0current). You can specify an alternative frame buffer device by setting the environment variable $FRAMEBUFFER to the path name of a frame buffer device, e.g. (for sh/bash -users): +users):: export FRAMEBUFFER=/dev/fb1 -or (for csh users): +or (for csh users):: setenv FRAMEBUFFER /dev/fb1 @@ -90,9 +90,9 @@ which data structures they work. Here's just a brief overview: possible). - You can get and set parts of the color map. Communication is done with 16 - bits per color part (red, green, blue, transparency) to support all - existing hardware. The driver does all the computations needed to apply - it to the hardware (round it down to less bits, maybe throw away + bits per color part (red, green, blue, transparency) to support all + existing hardware. The driver does all the computations needed to apply + it to the hardware (round it down to less bits, maybe throw away transparency). All this hardware abstraction makes the implementation of application programs @@ -113,10 +113,10 @@ much trouble... 3. Frame Buffer Resolution Maintenance -------------------------------------- -Frame buffer resolutions are maintained using the utility `fbset'. It can +Frame buffer resolutions are maintained using the utility `fbset`. It can change the video mode properties of a frame buffer device. Its main usage is -to change the current video mode, e.g. during boot up in one of your /etc/rc.* -or /etc/init.d/* files. +to change the current video mode, e.g. during boot up in one of your `/etc/rc.*` +or `/etc/init.d/*` files. Fbset uses a video mode database stored in a configuration file, so you can easily add your own modes and refer to them with a simple identifier. @@ -129,8 +129,8 @@ The X server (XF68_FBDev) is the most notable application program for the frame buffer device. Starting with XFree86 release 3.2, the X server is part of XFree86 and has 2 modes: - - If the `Display' subsection for the `fbdev' driver in the /etc/XF86Config - file contains a + - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config + file contains a:: Modes "default" @@ -146,7 +146,7 @@ XFree86 and has 2 modes: same virtual desktop size. The frame buffer device that's used is still /dev/fb0current (or $FRAMEBUFFER), but the available resolutions are defined by /etc/XF86Config now. The disadvantage is that you have to - specify the timings in a different format (but `fbset -x' may help). + specify the timings in a different format (but `fbset -x` may help). To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't work 100% with XF68_FBDev: the reported clock values are always incorrect. @@ -172,29 +172,29 @@ retrace, the electron beam is turned off (blanked). The speed at which the electron beam paints the pixels is determined by the dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions -of cycles per second), each pixel is 35242 ps (picoseconds) long: +of cycles per second), each pixel is 35242 ps (picoseconds) long:: 1/(28.37516E6 Hz) = 35.242E-9 s -If the screen resolution is 640x480, it will take +If the screen resolution is 640x480, it will take:: 640*35.242E-9 s = 22.555E-6 s to paint the 640 (xres) pixels on one scanline. But the horizontal retrace -also takes time (e.g. 272 `pixels'), so a full scanline takes +also takes time (e.g. 272 `pixels`), so a full scanline takes:: (640+272)*35.242E-9 s = 32.141E-6 s -We'll say that the horizontal scanrate is about 31 kHz: +We'll say that the horizontal scanrate is about 31 kHz:: 1/(32.141E-6 s) = 31.113E3 Hz A full screen counts 480 (yres) lines, but we have to consider the vertical -retrace too (e.g. 49 `lines'). So a full screen will take +retrace too (e.g. 49 `lines`). So a full screen will take:: (480+49)*32.141E-6 s = 17.002E-3 s -The vertical scanrate is about 59 Hz: +The vertical scanrate is about 59 Hz:: 1/(17.002E-3 s) = 58.815 Hz @@ -212,7 +212,7 @@ influenced by the moments at which the synchronization pulses occur. The following picture summarizes all timings. The horizontal retrace time is the sum of the left margin, the right margin and the hsync length, while the vertical retrace time is the sum of the upper margin, the lower margin and the -vsync length. +vsync length:: +----------+---------------------------------------------+----------+-------+ | | ↑ | | | @@ -256,7 +256,8 @@ The frame buffer device expects all horizontal timings in number of dotclocks 6. Converting XFree86 timing values info frame buffer device timings -------------------------------------------------------------------- -An XFree86 mode line consists of the following fields: +An XFree86 mode line consists of the following fields:: + "800x600" 50 800 856 976 1040 600 637 643 666 < name > DCF HR SH1 SH2 HFL VR SV1 SV2 VFL @@ -271,19 +272,27 @@ The frame buffer device uses the following fields: - vsync_len: length of vertical sync 1) Pixelclock: + xfree: in MHz + fb: in picoseconds (ps) pixclock = 1000000 / DCF 2) horizontal timings: + left_margin = HFL - SH2 + right_margin = SH1 - HR + hsync_len = SH2 - SH1 3) vertical timings: + upper_margin = VFL - SV2 + lower_margin = SV1 - VR + vsync_len = SV2 - SV1 Good examples for VESA timings can be found in the XFree86 source tree, @@ -303,9 +312,10 @@ and to the following documentation: - The manual pages for fbset: fbset(8), fb.modes(5) - The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5) - The mighty kernel sources: - o linux/drivers/video/ - o linux/include/linux/fb.h - o linux/include/video/ + + - linux/drivers/video/ + - linux/include/linux/fb.h + - linux/include/video/ @@ -330,14 +340,14 @@ and on its mirrors. The latest version of fbset can be found at - http://www.linux-fbdev.org/ + http://www.linux-fbdev.org/ + + +10. Credits +----------- - -10. Credits ----------- - This readme was written by Geert Uytterhoeven, partly based on the original -`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was +`X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was provided by Frank Neumann. The frame buffer device abstraction was designed by Martin Schaller. diff --git a/Documentation/fb/gxfb.txt b/Documentation/fb/gxfb.rst similarity index 60% rename from Documentation/fb/gxfb.txt rename to Documentation/fb/gxfb.rst index 2f640903bbb2..5738709bccbb 100644 --- a/Documentation/fb/gxfb.txt +++ b/Documentation/fb/gxfb.rst @@ -1,7 +1,8 @@ -[This file is cloned from VesaFB/aty128fb] - +============= What is gxfb? -================= +============= + +.. [This file is cloned from VesaFB/aty128fb] This is a graphics framebuffer driver for AMD Geode GX2 based processors. @@ -23,9 +24,9 @@ How to use it? ============== Switching modes is done using gxfb.mode_option=... boot -parameter or using `fbset' program. +parameter or using `fbset` program. -See Documentation/fb/modedb.txt for more information on modedb +See Documentation/fb/modedb.rst for more information on modedb resolutions. @@ -42,11 +43,12 @@ You can pass kernel command line options to gxfb with gxfb.