OpenGLES overview

This article gives information about the Linux^® OpenGL^® ES framework used to program GPU-based 2D and 3D graphic applications.

Framework purpose

The objective of this chapter is to give general information about the XXX framework.

Explain in few words the main functions, features of the XXX framework (what is it for?). See examples in IIO overview#Framework_purpose or in Crypto API overview#Framework_purpose.

You can use the following sentence to introduce the XXX framework: "the XXX framework is dedicated to... / mainly includes functions for...".

Optionally, add here general information that will help the readers understand how this article may be useful.

If applicable, give a list of use cases that involve, among others, the XXX framework. In other words, it is a way to share with the readers some common situations in which the XXX framework is used.
See examples in IIO overview#Framework purpose.
Generally speaking, these use cases will not be detailed in the user guide. However, if it is the case for few of them, it will be in dedicated articles named "Use case AAA".
You can use the following sentence to introduce the use cases list: "Example(s) of use case(s) involving the XXX framework:".

System overview

The objective of this chapter is to identify and describe the main components and APIs of the XXX framework:

• Insert here a system architecture diagram that identifies the components and APIs of the XXX framework:
  • See Contributors:Diagram model to have the look and feel mandatory for diagram publication
• Optionally add a short description of the framework role and features.
• If needed, add references to "parent" overview articles (e.g. link to Overview of GPIO pins in Pinctrl overview and in GPIOLib overview).

Component description

<securetransclude src="ProtectedTemplate:ReviewsComments" params="GeraldB: the title should rather be "Components description""></securetransclude>{{#set:Has reviews comments=true}}

Detail the roles of each component identified in the diagram.

You can optionally separate the descriptions of the user space, kernel space and hardware components, with subchapters or bullets respectively name "User space", "Kernel space" and "Hardware". This presentation is especially pertinent if the components description takes lot of lines.

API description

Detail each API identified in the diagram (user space API, kernel space API, debugfs API...):

• Give links to Web pages such as (non-exhaustive list):
  • Linux driver implementer’s API guide
  • Kernel Documentation directory

You can optionally separate the descriptions of the user space and kernel space (even sysf, debugfs...) interfaces, with subchapters or bullets respectively name "User space interface" and "Kernel space interface" (even "sysfs interface", "Debugfs interface"...). This presentation is especially pertinent if the components description takes lot of lines.

Configuration

The objective of this chapter is to explain how to configure the Linux kernel and device tree to have the XXX framework activated.

Kernel configuration

You can use one of the following sentences, depending on your situation:

• "XXX is activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how XXX can be activated/deactivated in the kernel."
• "XXX is activated by default in ST deliveries, and can not be deactivated."

If XXX can be activated/deactivated, explain the Linux kernel configuration with the following sentence and Menuconfig path (see examples in IIO overview#Kernel Configuration or in PWM overview#Kernel Configuration)

Activate XXX in kernel configuration with Linux Menuconfig tool: Menuconfig or how to configure kernel (specify the activated configuration options: CONFIG_AAA, CONFIG_BBB...):

Device Drivers  --->
  ... --->
    ...

Device tree configuration

The XXX framework generic DT bindings and the detailed DT configuration for STM32 internal peripherals associated with the XXX framework must be described in dedicated (separated) articles (one per internal peripheral) that follow the Contributors:Peripheral or framework device tree configuration model. Indeed, these articles might be referenced not only in "internal peripheral" articles, but also in "internal peripheral Linux driver" articles and in "framework overview" articles.

However, if the XXX framework is associated with several STM32 internal peripherals, it might be pertinent to refer here to the common parts of the DT configuration.

See examples in GPIOLib overview#Device tree configuration or in IIO overview#Device tree configuration

Use the following generic bullet if there are common parts of the DT configuration to explain to the the readers

XXX generic DT bindings:

• ...

Detailed DT configuration for STM32 internal peripherals:

• Links to internal peripheral device tree configuration articles

How to use the framework

The objective of this chapter is to explain to the readers how to use the XXX framework and its underlying Linux drivers and internal peripherals.

To detail a little more, "how to use" aims, to demonstrate that these elements (framework, drivers and internal peripherals) are working correctly, to show how to use the APIs listed in #API description, and to help the readers to create their own applications on top of these elements.

"How to use" could take different forms from simple command lines to execute standard Linux tools, complex scripts (Python, Perl...), standard applications (e.g. GStreamer video player, Java applications...), to standard or ST specific C code.

The objectives and levels defined for the Linux examples fit with the needs of this chapter. So, generally speaking, it might be enough to link here to the "how to" articles written for the Linux examples. See example in IIO overview#How to use the framework. Note that these "how to" articles might be referenced not only in the "framework overview" articles, but also in the "internal peripheral Linux driver" articles.

Obviously, additional information that you consider out of the "how to" articles scope, might be added in this chapter. This information might be source code, that explains how to use the APIs, but that is not a complete buildable C application. See example in Pinctrl overview#How to use the framework.

How to trace and debug the framework

The objective of this chapter is to give methods to monitor, trace and debug the XXX framework. This chapter must be present: it is mandatory to have at least one method presented.

How to monitor

Give instructions to help developer/user to get information about this framework in the Linux file system. Monitoring is understood here as getting static status about the framework.

How to monitor with debugfs

Other ways of monitoring

Up to framework owner to add any relevant other ways to monitor the framework (e.g. device entry, sysfs, procfs...).

How to trace

Give instructions to help developer/user for getting trace(s)via:

• dynamic debug if exist,
• specific log files if exist,
• dmesg output information,
• ...

Tracing is understood here as getting dynamic logs about the framework.

Up to framework owner to add any relevant other ways to trace the framework.

How to debug

Give recommendations and tips to developers/users for debugging this framework:

• How to efficiently use the monitoring and trace instructions presented above to debug some "well-known" problems
• How to proceed face to some critical situations (e.g. error messages). Note that there are several ways to describe the debugging procedure:
  • It might be enough to link to a Web article
  • If the explanation takes few lines, a subchapter (or a bullet) is enough
  • If the explanation is long, a dedicated "how to" article is recommended
• Other instructions than the ones presented in the monitoring and trace subchapters above might be proposed
• It might also be interesting to highlight some Trace and debug tools that are very helpful to debug the XXX framework

Source code location

The objective of this chapter is to indicate the location of the XXX framework source code.

See the example in GPIOLib overview#Source code location.

You can use the following way to present the source code location: "The XXX framework is composed of:"

• Set links to the files (".c", ".h", ".txt"...) thanks to the Template:CodeSource. See examples in Template:CodeSource#Example.

To go further

The objective of this chapter is to give extra information such as links to online trainings, recommended books, tips and tricks that it is not pertinent to put in the other chapters.

References

<securetransclude src="ProtectedTemplate:ArticleBasedOnModel" params="Framework overview article model"></securetransclude> <securetransclude src="ProtectedTemplate:PublicationRequestId" params="| 2019-01-28 | Jean-ChristopheT, Automatic approval (article under construction)"></securetransclude>