The "os" class, declared in os.hpp, forms the major part of the HotSpot porting interface. It's structure has gradually deteriorated over the years as new ports are created and new APIs are added.

This RFE tries to address the following:

- Clearly specify where a porting API should be declared and defined among the various os*.cpp and os*.hpp files.
- Avoid the inappropriate inclusion of OS-specific APIs (such as the os::Linux class) by platform-independent source files.

The updated specification:

// Rules for using and implementing methods declared in the "os" class
// ===================================================================
//
// The "os" class defines a number of the interfaces for porting HotSpot
// to different operating systems. For example, I/O, memory, timing, etc.
// Note that additional classes such as Semaphore, Mutex, etc., are used for
// porting specific groups of features.
//
// Structure of os*.{cpp, hpp} files
//
// - os.hpp
//
// (This file) declares the entire API of the "os" class.
//
// - os.inline.hpp
//
// To use any of the inline methods declared in the "os" class, this
// header file must be included.
//
// - src/hotspot/os/<os>/os_<os>.hpp
// - src/hotspot/os/posix/os_posix.hpp
//
// These headers declare APIs that should be used only within the
// platform-specific source files for that particular OS.
//
// For example, os_linux.hpp declares the os::Linux class, which provides
// many methods that can be used by files under os/linux/ and os_cpu/linux_*/
//
// os_posix.hpp can be used by platform-specific files for POSIX-like
// OSes such as aix, bsd and linux.
//
// Platform-independent source files should not include these header files
// (although sadly there are some rare exceptions ...)
//
// - os.cpp
//
// Platform-independent methods of the "os" class are defined
// in os.cpp. These are not part of the porting interface, but rather
// can be considered as convenience functions for accessing
// the porting interface. E.g., os::print_function_and_library_name().
//
// The methods declared in os.hpp but not implemented in os.cpp are
// a part the HotSpot Porting APIs. They must be implemented in one of
// the following four files:
//
// - src/hotspot/os/<os>/os_<os>.inline.hpp
// - src/hotspot/os_cpu/<os>_<cpu>/os_<os>_<cpu>.inline.hpp
// - src/hotspot/os/<os>/os_<os>.cpp
// - src/hotspot/os_cpu/<os>_<cpu>/os_<os>_<cpu>.cpp
//
// The Porting APIs declared as "inline" in os.hpp MUST be
// implemented in one of the two .inline.hpp files, depending on
// whether the feature is specific to a particular CPU architecture
// for this OS. These two files are automatically included by
// os.inline.hpp. Platform-independent source files must not include
// these two files directly.
//
// If the full definition of an inline method is too complex to fit in a
// header file, the actual implementation can be deferred to another
// method defined in the .cpp files.
//
// The Porting APIs that are *not* declared as "inline" in os.hpp MUST
// be implemented in one of the two .cpp files above. These files
// also implement OS-specific APIs such as os::Linux, os::Posix, etc.
//
// (Note: on the POSIX-like platforms, some of the Porting APIs are implemented
// in os_posix.cpp instead).