{"id":19297237,"url":"https://github.com/HSAFoundation/CLOC","last_synced_at":"2025-04-22T09:30:27.628Z","repository":{"id":54523642,"uuid":"21188294","full_name":"HSAFoundation/CLOC","owner":"HSAFoundation","description":"CL Offline Compiler : Compile OpenCL kernels to HSAIL","archived":false,"fork":false,"pushed_at":"2017-05-05T07:36:25.000Z","size":983904,"stargazers_count":49,"open_issues_count":11,"forks_count":18,"subscribers_count":63,"default_branch":"master","last_synced_at":"2024-11-09T23:02:25.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HSAFoundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-25T02:57:04.000Z","updated_at":"2024-05-19T05:48:34.000Z","dependencies_parsed_at":"2022-08-13T18:40:11.481Z","dependency_job_id":null,"html_url":"https://github.com/HSAFoundation/CLOC","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HSAFoundation%2FCLOC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HSAFoundation%2FCLOC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HSAFoundation%2FCLOC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HSAFoundation%2FCLOC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HSAFoundation","download_url":"https://codeload.github.com/HSAFoundation/CLOC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250214913,"owners_count":21393695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T23:01:48.967Z","updated_at":"2025-04-22T09:30:26.401Z","avatar_url":"https://github.com/HSAFoundation.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"CLOC - V 1.3.2\n==============\n\nCLOC:  CL Offline Compiler\n       Generate HSA code object from a cl (Kernel c Language) file.\nSNACK: Structured No API Compiled Kernels.\n       Launch GPU kernels as host-callable functions with structured launch parameters.\n\nTable of contents\n-----------------\n\n- [Copyright and Disclaimer](#Copyright)\n- [Software License Agreement](LICENSE.TXT)\n- [Command Help](#CommandHelp)\n- [Examples](#ReadmeExamples)\n- [Install](INSTALL.md)\n\n\u003cA NAME=\"Copyright\"\u003e\n# Copyright and Disclaimer\n------------------------\n\nCopyright (c) 2016 ADVANCED MICRO DEVICES, INC.  \n\nAMD is granting you permission to use this software and documentation (if any) (collectively, the \n“Materials”) pursuant to the terms and conditions of the Software License Agreement included with the \nMaterials.  If you do not have a copy of the Software License Agreement, contact your AMD \nrepresentative for a copy.\n\nYou agree that you will not reverse engineer or decompile the Materials, in whole or in part, except for \nexample code which is provided in source code form and as allowed by applicable law.\n\nWARRANTY DISCLAIMER: THE SOFTWARE IS PROVIDED \"AS IS\" WITHOUT WARRANTY OF ANY \nKIND.  AMD DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT \nLIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR \nPURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL RUN UNINTERRUPTED OR ERROR-\nFREE OR WARRANTIES ARISING FROM CUSTOM OF TRADE OR COURSE OF USAGE.  THE ENTIRE RISK \nASSOCIATED WITH THE USE OF THE SOFTWARE IS ASSUMED BY YOU.  Some jurisdictions do not \nallow the exclusion of implied warranties, so the above exclusion may not apply to You. \n\nLIMITATION OF LIABILITY AND INDEMNIFICATION:  AMD AND ITS LICENSORS WILL NOT, \nUNDER ANY CIRCUMSTANCES BE LIABLE TO YOU FOR ANY PUNITIVE, DIRECT, INCIDENTAL, \nINDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE OR THIS \nAGREEMENT EVEN IF AMD AND ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH \nDAMAGES.  In no event shall AMD's total liability to You for all damages, losses, and \ncauses of action (whether in contract, tort (including negligence) or otherwise) \nexceed the amount of $100 USD.  You agree to defend, indemnify and hold harmless \nAMD and its licensors, and any of their directors, officers, employees, affiliates or \nagents from and against any and all loss, damage, liability and other expenses \n(including reasonable attorneys' fees), resulting from Your use of the Software or \nviolation of the terms and conditions of this Agreement.  \n\nU.S. GOVERNMENT RESTRICTED RIGHTS: The Materials are provided with \"RESTRICTED RIGHTS.\" \nUse, duplication, or disclosure by the Government is subject to the restrictions as set \nforth in FAR 52.227-14 and DFAR252.227-7013, et seq., or its successor.  Use of the \nMaterials by the Government constitutes acknowledgement of AMD's proprietary rights in them.\n\nEXPORT RESTRICTIONS: The Materials may be subject to export restrictions as stated in the \nSoftware License Agreement.\n\n\u003cA NAME=\"CommandHelp\"\u003e\n# Command Help \n--------- \n## The cloc.sh command \n\n```\n   cloc.sh: Compile a cl or cu file into an HSA Code object file (.hsaco)  \n            using the LLVM Ligntning Compiler. An hsaco file contains \n            the amdgpu isa that can be loaded by the HSA Runtime.\n            As of amdcloc 1.3.1, use of cuda is only experimental.  \n            Generated kernels from cuda will not execute. \n\n   Usage: cloc.sh [ options ] filename.cl\n\n   Options without values:\n    -ll       Generate IR for LLVM steps before generating hsaco\n    -s        Generate dissassembled gcn from hsaco\n    -g        Generate debug information\n    -noqp     No quickpath, Use LLVM commands instead of clang driver\n    -noshared Do not link hsaco as shared object, forces noqp\n    -version  Display version of cloc then exit\n    -v        Verbose messages\n    -n        Dryrun, do nothing, show commands that would execute\n    -h        Print this help message\n    -k        Keep temporary files\n    -brig     Generate brig instead of hsaco (deprecated)\n    -hsail    Generate dissassembled hsail for brig  (deprecated)\n\n   Options with values:\n    -amdllvm   \u003cpath\u003e           $AMDLLVM or /opt/amd/llvm\n    -libgcn    \u003cpath\u003e           $LIBGCN or /opt/rocm/libamdgcn  \n    -hlcpath   \u003cpath\u003e           $HLC_PATH or /opt/rocm/hlc3.2/bin  \n    -cuda-path \u003cpath\u003e           $CUDA_PATH or /usr/local/cuda\n    -mcpu      \u003ccputype\u003e        Default= value returned by mymcpu\n    -bclib     \u003cbcfile\u003e         Add a bc library for llvm-link\n    -clopts    \u003ccompiler opts\u003e  Addtional options for cl frontend\n    -cuopts    \u003ccompiler opts\u003e  Additonal options for cu frontend\n    -I         \u003cinclude dir\u003e    Provide one directory per -I option\n    -lkopts    \u003cLLVM link opts\u003e Default=$LIBGCN/lib/libamdgcn.$mcpu.bc\n    -hsaillib  \u003cfname\u003e          Filename of hsail library. (deprecated)\n    -opt       \u003cLLVM opt\u003e       LLVM optimization level\n    -o         \u003coutfilename\u003e    Default=\u003cfilename\u003e.\u003cft\u003e ft=brig or hsail\n    -t         \u003ctdir\u003e           Temporary directory or intermediate files\n                                Default=/tmp/cloc-tmp-$$\n   Examples:\n    cloc.sh my.cl             /* creates my.hsaco                    */\n    cloc.sh whybother.cu      /* creates whybother.hsaco             */\n\n   Note: Instead of providing these command line options:\n   -opt,-hlcpath,-amdllvm,-libgcn,-cuda-path,-mcpu,-clopts, or -lkopts \n\n   You may set these environment variables, respectively:\n   LLVMOPT,HLC_PATH,AMDLLVM,LIBGCN,CUDA_PATH,LC_MCPU,CLOPTS, or LKOPTS \n\n   Command line options will take precedence over environment variables. \n\n   Copyright (c) 2016 ADVANCED MICRO DEVICES, INC.\n\n```\n\n\n## The snack.sh Command \n\n```\n   snack: Generate host-callable \"snack\" functions for GPU kernels.\n          Snack generates the source code and headers for each kernel \n          in an OpenCL cl or CUDA cu file.  The -c option will compile \n          the source with gcc so you can link with your host application.\n          Host applicaton requires no API to use snack functions.\n\n   Usage: snack.sh [ options ] filename.cl\n\n   Options without values:\n    -c        Compile generated source code to create .o file\n    -ll       Tell cloc.sh to generate IR for LLVM steps\n    -noqp     Tell cloc.sh to not use quick path\n    -noshared Tell cloc.sh to not create shared object.\n    -s        Generate gcn assembly (.s) from lld output\n    -version  Display version of snack then exit\n    -v        Verbose messages\n    -vv       Get additional verbose messages from cloc.sh\n    -n        Dryrun, do nothing, show commands that would execute\n    -h        Print this help message\n    -k        Keep temporary files\n    -fort     Generate fortran function names\n    -noglobs  Do not generate global functions \n    -kstats   Print out code object kernel statistics \n    -m32      Generate snackwrap in 32-bit mode. If -c, also compile in 32\n              bit mode\n\n   Options with values:\n    -path      \u003cpath\u003e         $CLOC_PATH or \u003csdir\u003e if CLOC_PATH not set\n                              \u003csdir\u003e is directory where snack.sh is found\n    -mcpu      \u003ccpu\u003e          Default=`'mymcpu`, Options: kaveri,carrizo,fiji\n    -amdllvm   \u003cpath\u003e         Default=/opt/amd/llvm or env var AMDLLVM \n    -libgcn    \u003cpath\u003e         Default=/opt/rocm/libamdgcn or env var LIBGCN \n    -cuda-path \u003cpath\u003e         $CUDA_PATH or /usr/local/cuda\n    -I        \u003cinclude dir\u003e  Provide one directory per -I option for cloc.sh\n    -bclib    \u003cbcfile\u003e       Add a bc library for llvm-link\n    -opt      \u003cLLVM opt\u003e     Default=2, passed to cloc.sh to build code object\n    -gccopt   \u003cgcc opt\u003e      Default=2, gcc optimization for snack wrapper\n    -t        \u003ctempdir\u003e      Default=/tmp/snk_$$, Temp dir for files\n    -s        \u003csymbolname\u003e   Default=filename \n    -hsart    \u003cHSA RT\u003e       Default=CLOC_PATH/..\n    -o        \u003coutfilename\u003e  Default=\u003cfilename\u003e.\u003cft\u003e \n    -foption  \u003cfnlizer opts\u003e Default=\"\"  Finalizer options\n\n   Examples:\n    snack.sh my.cl              /* create my.snackwrap.c and my.h    */\n    snack.sh -c my.cl           /* gcc compile to create  my.o       */\n    snack.sh -c whybother.cl    /* compile to create  whybother.o    */\n    snack.sh -t /tmp/foo my.cl  /* will automatically set -k         */\n\n   Instead of providing these command line options:\n   -path,-hsart,-amdllvm,-libgcn,-cuda-path,-mcpu\n\n   You may set these environment variables respectively:\n   CLOC_PATH,HSA_RT,AMDLLVM,LIBGCN,CUDA_PATH,LC_MCPU\n\n   Command line options will take precedence over environment variables. \n\n   Copyright (c) 2016 ADVANCED MICRO DEVICES, INC.\n\n```\n\n\u003cA NAME=\"ReadmeExamples\"\u003e\n# Examples\n-------- \n\n## Example 1: Hello World\n\nThis version of cloc supports the SNACK method of writing accelerated \nkernels in c. With SNACK, the host program can directly call the accelerated \nfunction without an API such as OpenCL or CUDA.\n\nHere is the c++ source code HelloWorld.cpp using SNACK.\n```cpp\n#include \u003cstring.h\u003e\n#include \u003cstdlib.h\u003e\n#include \u003ciostream\u003e\nusing namespace std;\n#include \"hw.h\"\nint main(int argc, char* argv[]) {\n\tconst char* input_const = \"Gdkkn\\x1FGR@\\x1FVnqkc\";\n\tsize_t strlength = strlen(input_const);\n\tchar *output = (char*) malloc_global(strlength + 1);\n\tchar *input = (char*) malloc_global(strlength + 1);\n        strncpy(input,input_const,strlength);\n        SNK_INIT_LPARM(lparm,strlength);\n        decode(input,output,lparm);\n\toutput[strlength] = '\\0';\n\tcout \u003c\u003c output \u003c\u003c endl;\n\tfree_global(output);\n\tfree_global(input);\n\treturn 0;\n}\n```\nThe c source for the accelerated kernel is in file hw.cl.\n```c\n/*\n    File:  hw.cl \n*/\n__kernel void decode(__global const char* in, __global char* out) {\n\tint num = get_global_id(0);\n\tout[num] = in[num] + 1;\n}\n```\nThe -c option of snack.sh will call the gcc compiler and create \nthe object file and the header file \"hw.h\" required to build \nthe host program. Without -c you get the generated c code hw.snackwrap.c \nand the header file.  The header file has the function prototypes \nfor all kernels declared in the .cl file.  Use this command to \ncompile the hw.cl file with snack.sh.\n\n```\nsnack.sh -c hw.cl\n```\n\nYou can now compile and build the binary \"HelloWorld\" with any c++ compiler.\nHere is the command to build HelloWorld with g++. \n\n```\ng++ -o HelloWorld hw.o HelloWorld.cpp -L/opt/rocm/lib -lhsa-runtime64 -lelf \n\n```\n\nThen execute the program as follows.\n```\n$ ./HelloWorld\nHello HSA World\n```\n\nThis example and other examples can be found in the cloc examples directory found in /opt/rocm/cloc/examples\n\n\n## Example 2: Use of -hsaillib by cloc.sh and snackhsail.sh\n\nThe snack.sh command creates and embeds HSA code object or isa.  To create and embed the HSAIL intermediate\nlanguage you can use the snackhsail.sh command in an similar way. \n\nThe snackhsail.sh command has an additional option to provide an HSAIL library.\nThis options specifies a single file with the hsail for multiple functions that can be \ncalled directly by cl.  One should have a corresponding header file for these functions.  \nAn example to use the -hsaillib option is provided in the directory examples/snack/test_hsail_lib. \nThis example uses the simple HSAIL library provided in the directory examples/mathdemo_hsaillib\n\nHere you see the header file and the corresponding hsail file. This is the contents of \nthe header file mathdemo_hsaillib.h. \n```\nfloat __sin(float in);\nfloat __cos(float in);\nfloat __exp(float in);\n```\nThe example cl file (examples/snack/test_hsail_lib/test_hsail_lib.cl) includes the above header file. \n```\n#include \"../../mathdemo_hsaillib/mathdemo_hsaillib.h\"\n__kernel void testkernel( __global float * outfval , __global const float  * fval) {\n   int i = get_global_id(0);\n   outfval[i] =  __sin(fval[i]);\n}\n```\nIf you want to compile and build the example, execute the buildrun.sh script found\nin the example directory.  It calls snackhsail.sh as follows:\n```\nsnackhsail.sh  -v -c  -hsaillib ../../mathdemo_hsaillib/mathdemo_hsaillib.hsail test_hsail_lib.cl\n```\nIf you are just building the hsail for the above kernel, provide the -hsaillib option to cloc.sh\nas follows.\n```\ncloc.sh -hsail -hsaillib ../../mathdemo_hsaillib/mathdemo_hsaillib.hsail test_hsail_lib.cl\n```\nYour resulting hsail test_hsail_lib.hsail will include the hsaillib inserted into the correct\nposition. The generated brig will also include the library. \n\n## Example 3: Creating code object file with GCN isa and loading it with HSA API.\n\nIn it's simplest form, cloc.sh compiles a .cl file into an HSA code object file.   This is a standard ELF file that can be loaded by the HSA API without the need for finalization.   However, the rest of the HSA API is required to launch this object code to the GPU.  An example is provided in the examples/hsa directory that shows the necessary HSA API to launch an HSA code object.  Use these commands to run this example:\n```\ncd $HOME\ncp -rp /opt/rocm/cloc/examples/hsa/vector_copy_codeobject_rocm /tmp\ncd /tmp/vector_copy_codeobject_rocm\nmake\nmake test\n```\nThe make command will compile vector_copy_codeobject.cpp with these commands:\n```\ng++ -c -std=c++11 -I/opt/rocm/hsa/include -o obj/vector_copy_codeobject.o vector_copy_codeobject.cpp\ng++ obj/vector_copy_codeobject.o -L/opt/rocm/lib -lhsa-runtime64 -o vector_copy_codeobject\n```\nIt then calls cloc.sh to create the file vectory_copy_codeobject.hsaco with this command. \n```\ncloc.sh vector_copy_codeobject.cl\n```\nThe program will load the HSA code object file and launch it with the HSA API.  One could compare the minor difference in the HSA API between loading a code object and loading brig by comparing the source code and Makefile from the above example to the vector_copy example found in /opt/rocm/cloc/examples/hsa/vector_copy.   In the vector_copy example, cloc.sh requires the -brig option and the API source code in vector_copy.c has the extra finalization step. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHSAFoundation%2FCLOC","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHSAFoundation%2FCLOC","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHSAFoundation%2FCLOC/lists"}