Summary: An overview of the Production Quality OAL (PQOAL) initiative. Describes how two devices that use the same chipset/SoC can reuse OAL components using the libraries provided in platform\common.

---

Production Quality OAL (PQOAL) was introduced by Microsoft in Windows CE 5.0.

The basic tenets of Production Quality OAL code are:

		    *Code that is specific to a chipset/SoC should be separate from code specific to a particular implementation of that chipset/SoC.
		    *Code in the Board Support Package (BSP) should be componentized and organized logically.
		    *All chipset, system-on-chip, and BSP code should be of high quality so that it can be easily reused.
	

The PQOAL Directory structure in CE6.0:

		    platform\common:
		        Where all of the reusable code lives.  It builds after the sysgen phase of the build but before BSP build.
	

		    platform\common\src\common:
		        Generic code that is reusable by the BSP but is not specific to any hardware implementation.  Examples include common IOCTL handlers, common interrupt routines for interfacing with the kernel, etc.  Libraries such as oal_ioctl.lib, oal_intr.lib, oal_log.lib, and kitl_log.lib are built here.  This is Microsoft-provided code that you should not modify.
	

		    platform\common\src\<CPU>:
		        Code specific to particular x86, SH, MIPS, and ARM [CPUs.]  This may include cache code to support a particular CPU, or on-chip timer code.  Libraries such as oal_cache_arm920t and oal_timer_mips_fixtick are built here.  This is Microsoft-provided code that you should not modify.
	

		    platform\common\src\soc:
		        Code specific to a particular system-on-chip or to a chip support package.  This is where drivers, OAL, catalog, and other supporting code for a CSP or SoC go.  While you should not modify the code provided in this directory, you can add a new directory of your own to provide your own CSP/SoC code.  All of the libraries and dynamic-link-libraries built in the SoC directory contain their SoC directory name to avoid naming conflicts.
	

		    platform\common\src\soc layout:
		        \<soc name>_<vendor abbreviation>_<version number> - root directory for the SoC/CSP code.  It's important to follow the naming convention closely to avoid naming conflicts, since any third party can ship code in the SoC directory.
		            \inc     - headers and includes
		            \catalog - catalog files for the SoC
		            \serial  - individual driver directory
		            \display - individual driver directory
		            \...     - other driver directories
		            \oal  
		            \rtc   - rtc code for linking with the oal
		            \intr  - interrupt code for linking the the oal
	

Guidelines for implementing your custom SoC directory:

		    *Follow the naming convention, <soc name> _ <vendor name> _ <version>, for the directory name and all library names.
		    *The dirs file in your custom SoC directory should correspond to the CPU type that your SoC supports.  For example, an ARM-based SoC would have
		        DIRS_ARM=\
		            directory1 \
		            directory2 \
		    *Make sure that your code in the SoC directory is high quality!  Putting code in the SoC directory is your way of saying that it is fit for reuse.  So use good design practices, comment your code thoroughly, and avoid conditional compilation, because someone is bound to reuse it!
	

		    [platform\<BSPName>:] This directory is where all of the board-specific code lives.  It will build after all of the platform\common code.
		        \catalog  - catalog files for the BSP
		        \cesysgen - where BSP .bib and .reg files are stored after processing by the build
		        \files    - .bib, .reg, and other non-code files for the BSP
		        \src      - all of the BSP source code
		            \bootloader - initial bootstrap code to get the CE image onto the device over a transport (serial, ethernet, USB, etc.)
		            \common - code shared between bootloader, oal, drivers, etc.
		            \drivers   - BSP drivers, typically dynamic-link-libraries
		            \serial  - individual driver, may link with SoC code
		            \display - individual driver, may link with SoC code
		            \inc       - headers and includes
		            \kitl   - Kernel Independent Transport Layer (KITL), for communicating with platform builder and kernel.  kitl.dll builds here
		            \oal    
		                \oallib - BSP-specific OAL code
		                \oalexe - link the BSP code with common and soc, oal.exe builds here
	

It is possible that you may want to reuse code from platform\common in your BSP, but you need to modify it in some minor way. Since you shouldn't modify code in the platform\common directories (with the exception of adding your own SoC directory), a common practice is to clone the code you need from platform\common into your BSP directory. You can clone common code, CPU code, or SoC code by simply copying. Since they're built using very similar processes, you should be able to copy platform\common code and modify the code to your liking without having to modify the build logic significantly.

Making your BSP follow the guidelines and structure above gives you a baseline for a high-quality BSP. You have a lot of freedom to architect the BSP directory how you like, but keeping the architecture simple and consistent makes the code easier to understand, port, and debug.

More information on changes to the OAL between CE 5.0 and CE 6.0 can be found on the CEBasebase team blog, "CE6 OAL: What you need to knowbase/archive/2006/11/21/ce6-oal-what-you-need-to-know.aspx"

---

Go up to Features of a BSP
Go up to Big Book of BSP

Thank you for contributing to this BSP Wiki. To ensure your comments and concerns receive proper exposure, include bspwiki""@""microsoft"".""com when providing feedback or topical suggestions.

---