1 /* Copyright 2014 The Chromium Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
8 * This file defines methods for mapping and unmapping files into and out of
13 [channel=dev] M34 = 0.1
17 * The PP_FileMapProtection values indicate the permissions requested for the
18 * file mapping. These should be used in a uint32_t bitfield.
21 enum PP_FileMapProtection {
22 /** Requests read access to the mapped address. */
23 PP_FILEMAPPROTECTION_READ = 1u << 0,
25 /** Requests write access to the mapped address. */
26 PP_FILEMAPPROTECTION_WRITE = 1u << 1
30 * The PP_FileMapFlags contain flag values for use with Map().
33 enum PP_FileMapFlags {
35 * Requests a shared mapping. If this flag is set, changes written to the
36 * memory region will be reflected in the underlying file and will thus
37 * eventually be visible to other processes which have opened the file. The
38 * file may not actually be updated until Unmap() is called. This is only
39 * valid if the PPB_FileIO resource was opened with write permission.
41 PP_FILEMAPFLAG_SHARED = 1u << 0,
44 * Requests a copy-on-write mapping. If this flag is set, changes are not
45 * written to the underlying file, but only in the memory of the process
48 PP_FILEMAPFLAG_PRIVATE = 1u << 1,
51 * Forces Map() to map the file contents at the provided |address|. If Map()
52 * can not comply, Map() will fail.
54 PP_FILEMAPFLAG_FIXED = 1u << 2
58 * PPB_FileMapping contains functions for mapping and unmapping files into and
62 interface PPB_FileMapping {
64 * Map() maps the contents from an offset of the file into memory.
66 * @param[in] instance A <code>PP_Instance</code> identifying one instance of
68 * @param[in] file_io A <code>PPB_FileIO</code> <code>PP_Resource</code>
69 * corresponding to the file that should be mapped in to memory.
70 * @param[in] length The number of bytes to map.
71 * @param[in] map_protection A bitfield containing values from
72 * <code>PP_FileMapProtection</code>, indicating what memory operations
73 * should be permitted on the mapped region.
74 * @param[in] map_flags A bitfield containing values from
75 * <code>PP_FileMapFlags</code>, providing options for the behavior of Map.
76 * If the region is to be writeable, then exactly one of
77 * <code>PP_FILEMAPFLAG_SHARED</code> or <code>PP_FILEMAPFLAG_PRIVATE</code>
79 * @param[in] offset The offset into the file. Must be a multiple of the
80 * Map page size as returned by GetMapPageSize().
81 * @param[inout] address The value of <code>*address</code>, if non-NULL,
82 * will be used as a hint to determine where in memory the file should be
83 * mapped. If the value is NULL, the host operating system will choose
84 * <code>address</code>. Upon Map() completing, <code>*address</code> will
85 * contain the actual memory location at which the file was mapped. If the
86 * plugin provides a non-NULL <code>*address</code>, it must be a multiple of
87 * the map page size as returned by GetMapPageSize().
88 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
89 * completion of Map().
91 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
93 int32_t Map([in] PP_Instance instance,
94 [in] PP_Resource file_io,
96 [in] uint32_t map_protection,
97 [in] uint32_t map_flags,
99 [inout] mem_ptr_t address,
100 [in] PP_CompletionCallback callback);
103 * Unmap() deletes the mapping of the specified address. The specified
104 * address must have been retrieved with Map().
105 * @param[in] instance A <code>PP_Instance</code> identifying the instance.
106 * @param[in] address The starting address of the address in memory to
108 * @param[in] length The length of the region to unmap.
109 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
110 * completion of Unmap().
112 * @return An int32_t containing an error code from <code>pp_errors.h</code>.
114 int32_t Unmap([in] PP_Instance instance,
117 [in] PP_CompletionCallback callback);
120 * GetMapPageSize() retrieves the size of pages that Map() uses.
122 * @param[in] instance A <code>PP_Instance</code> identifying the instance.
124 * @return The size of pages that Map() uses. Returns 0 on failure.
127 int64_t GetMapPageSize(PP_Instance instance);