/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * 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.
 */

package android.hardware.memtrack@1.0;

/**
 * The Memory Tracker HAL is designed to return information about
 * device-specific memory usage.
 * The primary goal is to be able to track memory that is not
 * trackable in any other way, for example texture memory that is allocated by
 * a process, but not mapped in to that process's address space.
 * A secondary goal is to be able to categorize memory used by a process into
 * GL, graphics, etc. All memory sizes must be in real memory usage,
 * accounting for stride, bit depth, rounding up to page size, etc.
 *
 * Constructor for the interface should be used to perform memtrack management
 * setup actions and is called once before any calls to getMemory().
 */
interface IMemtrack {
    /**
     * getMemory() populates MemtrackRecord vector with the sizes of memory
     * plus associated flags for that memory.
     *
     * This function must be thread-safe, it may get called from multiple
     * threads at the same time.
     *
     * A process collecting memory statistics will call getMemory for each
     * combination of pid and memory type. For each memory type that it
     * recognizes, the HAL must fill out an array of memtrack_record
     * structures breaking down the statistics of that memory type as much as
     * possible. For example,
     * getMemory(<pid>, GL) might return:
     * { { 4096,  ACCOUNTED | PRIVATE | SYSTEM },
     *   { 40960, UNACCOUNTED | PRIVATE | SYSTEM },
     *   { 8192,  ACCOUNTED | PRIVATE | DEDICATED },
     *   { 8192,  UNACCOUNTED | PRIVATE | DEDICATED } }
     * If the HAL cannot differentiate between SYSTEM and DEDICATED memory, it
     * could return:
     * { { 12288,  ACCOUNTED | PRIVATE },
     *   { 49152,  UNACCOUNTED | PRIVATE } }
     *
     * Memory must not overlap between types. For example, a graphics buffer
     * that has been mapped into the GPU as a surface must show up when
     * GRAPHICS is requested and not when GL
     * is requested.
     *
     * @param pid process for which memory information is requested
     * @param type memory type that information is being requested about
     * @return records vector of MemtrackRecord containing memory information
     * @return retval SUCCESS on success, TYPE_NOT_FOUND if the type is not
     * supported.
     */
    getMemory(int32_t pid, MemtrackType type)
            generates (MemtrackStatus retval, vec<MemtrackRecord> records);
};