control.h

Go to the documentation of this file.

/***************************************************************************
*   Copyright 2012 - 2013 Advanced Micro Devices, Inc.
*
*   Licensed under the Apache License, Version 2.0 (the "License");
*   you may not use this file except in compliance with the License.
*   You may obtain a copy of the License at
*
*       http://www.apache.org/licenses/LICENSE-2.0
*
*   Unless required by applicable law or agreed to in writing, software
*   distributed under the License is distributed on an "AS IS" BASIS,
*   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*   See the License for the specific language governing permissions and
*   limitations under the License.

***************************************************************************/


#pragma once
#if !defined( BOLT_CL_CONTROL_H )
#define BOLT_CL_CONTROL_H


#include <bolt/cl/bolt.h>
#include <string>
#include <map>

#include <boost/thread/mutex.hpp>
#include <boost/shared_ptr.hpp>

namespace bolt {
    namespace cl {

        class control {
        public:
            enum e_UseHostMode {NoUseHost, UseHost};
            enum e_RunMode     {Automatic,
                                SerialCpu,
                                MultiCoreCpu,
                                OpenCL };

            enum e_AutoTuneMode{NoAutoTune=0x0,
                                AutoTuneDevice=0x1,
                                AutoTuneWorkShape=0x2,
                                AutoTuneAll=0x3}; // FIXME, experimental
            struct debug {
                static const unsigned None=0;
                static const unsigned Compile = 0x1;
                static const unsigned ShowCode = 0x2;
                static const unsigned SaveCompilerTemps = 0x4;
                static const unsigned DebugKernelRun = 0x8;
                static const unsigned AutoTune = 0x10;
            };

            enum e_WaitMode {BalancedWait,  // Balance of Busy and Nice: tries to use Busy for short-running kernels.  \todo: Balanced currently maps to nice.
                             NiceWait,      // Use an OS semaphore to detect completion status.
                             BusyWait,      // Busy a CPU core continuously monitoring results.  Lowest-latency, but requires a dedicated core.
                             ClFinish,      // Call clFinish on the queue.
            };

        public:

            // Construct a new control structure, copying from default control for arguments that are not overridden.
            control(
                const ::cl::CommandQueue& commandQueue = getDefault().getCommandQueue(),
                e_UseHostMode useHost=getDefault().getUseHost(),
                unsigned debug=getDefault().getDebugMode()
                ) :
            m_commandQueue(commandQueue),
                m_useHost(useHost),
                m_forceRunMode(OpenCL),   //Replaced this with automatic because the default is not MultiCoreCPU if no GPU is found
                m_defaultRunMode(OpenCL),
                m_debug(debug),
                m_autoTune(getDefault().m_autoTune),
                m_wgPerComputeUnit(getDefault().m_wgPerComputeUnit),
                m_compileOptions(getDefault().m_compileOptions),
                m_compileForAllDevices(getDefault().m_compileForAllDevices),
                m_waitMode(getDefault().m_waitMode),
                m_unroll(getDefault().m_unroll)
            {};


            control( const control& ref) :
                m_commandQueue(ref.m_commandQueue),
                m_useHost(ref.m_useHost),
                m_forceRunMode(ref.m_forceRunMode),
                m_defaultRunMode(ref.m_defaultRunMode),
                m_debug(ref.m_debug),
                m_autoTune(ref.m_autoTune),
                m_wgPerComputeUnit(ref.m_wgPerComputeUnit),
                m_compileOptions(ref.m_compileOptions),
                m_compileForAllDevices(ref.m_compileForAllDevices),
                m_waitMode(ref.m_waitMode),
                m_unroll(ref.m_unroll)
            {
                //printf("control::copy construcor\n");
            };

            //setters:
            void setCommandQueue(::cl::CommandQueue commandQueue) { m_commandQueue = commandQueue; };

            void setUseHost(e_UseHostMode useHost) { m_useHost = useHost; };


            void setForceRunMode(e_RunMode forceRunMode) { m_forceRunMode = forceRunMode; };

            void setDebugMode(unsigned debug) { m_debug = debug; };

            void setWGPerComputeUnit(int wgPerComputeUnit) { m_wgPerComputeUnit = wgPerComputeUnit; };

            void setWaitMode(e_WaitMode waitMode) { m_waitMode = waitMode; };

            void setUnroll(int unroll) { m_unroll = unroll; };

            void setCompileOptions(std::string &compileOptions) { m_compileOptions = compileOptions; };

            // getters:
            ::cl::CommandQueue&         getCommandQueue( ) { return m_commandQueue; };
            const ::cl::CommandQueue&   getCommandQueue( ) const { return m_commandQueue; };
            ::cl::Context               getContext() const { return m_commandQueue.getInfo<CL_QUEUE_CONTEXT>();};
            ::cl::Device                getDevice() const { return m_commandQueue.getInfo<CL_QUEUE_DEVICE>();};
            e_UseHostMode               getUseHost() const { return m_useHost; };
            e_RunMode                   getForceRunMode() const { return m_forceRunMode; };
            e_RunMode                   getDefaultPathToRun() const { return m_defaultRunMode; };
            unsigned                    getDebugMode() const { return m_debug;};
            int const                   getWGPerComputeUnit() const { return m_wgPerComputeUnit; };
            const ::std::string         getCompileOptions() const { return m_compileOptions; };
            e_WaitMode                  getWaitMode() const { return m_waitMode; };
            int                         getUnroll() const { return m_unroll; };
            bool                        getCompileForAllDevices() const { return m_compileForAllDevices; };

            static control &getDefault()
            {
                // Default control structure; this can be accessed by the bolt::cl::control::getDefault()
                static control _defaultControl( true );
                return _defaultControl;
            };

            static void printPlatforms( bool printDevices = true, cl_device_type deviceType = CL_DEVICE_TYPE_ALL );
            static void printPlatformsRange( std::vector< ::cl::Platform >::iterator begin, std::vector< ::cl::Platform >::iterator end,
                                            bool printDevices = true, cl_device_type deviceType = CL_DEVICE_TYPE_ALL );

            static ::cl::CommandQueue getDefaultCommandQueue( );

            typedef boost::shared_ptr< ::cl::Buffer > buffPointer;

            size_t totalBufferSize( );
            buffPointer acquireBuffer( size_t reqSize, cl_mem_flags flags = CL_MEM_READ_WRITE, const void* host_ptr = NULL );
            void freeBuffers( );

        private:

            // This is the private constructor is only used to create the initial default control structure.
            control(bool createGlobal) :
                m_commandQueue( getDefaultCommandQueue( ) ),
                m_useHost(UseHost),
                m_debug(debug::None),
                m_autoTune(AutoTuneAll),
                m_wgPerComputeUnit(8),
                m_compileForAllDevices(true),
                m_waitMode(BusyWait),
                m_unroll(1)
            {
                ::cl_device_type dType = CL_DEVICE_TYPE_CPU;
                if(m_commandQueue() != NULL)
                {
                    ::cl::Device device = m_commandQueue.getInfo<CL_QUEUE_DEVICE>();
                    dType = device.getInfo<CL_DEVICE_TYPE>();
                }
                if(dType == CL_DEVICE_TYPE_CPU || m_commandQueue() == NULL)
                {
                    //m_commandQueue will be NULL if no platforms are found and
                    //if a non AMD paltform is found but cound not enumerate any CPU device
#ifdef ENABLE_TBB
                    m_forceRunMode = MultiCoreCpu;
                    m_defaultRunMode = MultiCoreCpu;
#else
                    m_forceRunMode = SerialCpu;
                    m_defaultRunMode = SerialCpu;
#endif
                }
                else
                {
                    //If dType = CL_DEVICE_TYPE_GPU
                    m_forceRunMode   = OpenCL;
                    m_defaultRunMode = OpenCL;
                }
            };

            ::cl::CommandQueue  m_commandQueue;
            e_UseHostMode       m_useHost;
            e_RunMode           m_forceRunMode;
            e_RunMode           m_defaultRunMode;
            e_AutoTuneMode      m_autoTune;  /* auto-tune the choice of device CPU/GPU and  workgroup shape */
            unsigned            m_debug;
            int                 m_wgPerComputeUnit;
            ::std::string       m_compileOptions;  // extra options to pass to OpenCL compiler.
            bool                m_compileForAllDevices;  // compile for all devices in the context.  False means to only compile for specified device.
            e_WaitMode          m_waitMode;
            int                 m_unroll;

            struct descBufferKey
            {
                ::cl::Context buffContext;
                cl_mem_flags memFlags;
                const void* host_ptr;
            };

            struct descBufferValue
            {
                size_t buffSize;
                bool inUse;
                ::cl::Buffer buffBuff;
            };

            struct descBufferComp
            {
                bool operator( )( const descBufferKey& lhs, const descBufferKey& rhs ) const
                {
                    if( lhs.memFlags < rhs.memFlags )
                    {
                        return true;
                    }
                    else if( lhs.memFlags == rhs.memFlags )
                    {
                        if( lhs.buffContext( ) < rhs.buffContext( ) )
                        {
                            return true;
                        }
                        else if( lhs.buffContext( ) == rhs.buffContext( ) )
                        {
                            if( lhs.host_ptr < rhs.host_ptr )
                            {
                                return true;
                            }
                            else
                            {
                                return false;
                            }
                        }
                        else
                        {
                            return false;
                        }
                    }
                    else
                    {
                        return false;
                    }
                }
            };

            typedef std::multimap< descBufferKey, descBufferValue, descBufferComp > mapBufferType;

            class UnlockBuffer
            {
                mapBufferType::iterator m_iter;
                control& m_control;

            public:
                //  Basic constructor requires a reference to the container and a positional element
                UnlockBuffer( control& p_control, mapBufferType::iterator it ): m_iter( it ), m_control( p_control )
                {}

                void operator( )( const void* pBuff )
                {
                    //  TODO: I think a general mutex is overkill here; we should try to use an interlocked instruction to modify the
                    //  inUse flag
                    boost::lock_guard< boost::mutex > lock( m_control.mapGuard );
                    m_iter->second.inUse = false;
                }
            };

            friend class UnlockBuffer;
            mapBufferType mapBuffer;
            boost::mutex mapGuard;

        }; // end class control

    };
};


// Implementor note:
// When adding a new field to this structure, don't forget to:
//   * Add the new field, ie "int _foo.
//   * Add setter function and getter function, ie "void foo(int fooValue)" and "int foo const { return _foo; }"
//   * Add the field to the private constructor.  This is used to set the global default "_defaultControl".
//   * Add the field to the public constructor, copying from the _defaultControl.

// Sample usage:
// bolt::control c(myCmdQueue);
// c.debug(bolt::control::ShowCompile);
// bolt::cl::reduce(c, a.begin(), a.end(), std::plus<int>);
//
//
// reduce (bolt::control(myCmdQueue),

#endif