Threading requirements of UsageTableHeader.

[ Merge of http://go/wvgerrit/148450 ]

This CL adds threading requirements to the method doc-comments of
UsageTableHeader.

Bug: 189366337
Test: usage_table_header_unittest
Change-Id: I671f702d3e8ec219cc8daaa220133cb8cec183c8

libwvdrmengine/cdm/core/include/usage_table_header.h

@@ -59,18 +59,30 @@ class UsageTableHeader {
   // If restoring fails, then a new usage table is created.
   // Note: No OEMCrypto session for the same security level should be
   // opened before calling.
+  // Threading: Method requires care of caller for exclusive access
+  // (ie. test setup or CryptoSession).
   bool Init(CdmSecurityLevel security_level, CryptoSession* crypto_session);
 
-  // |persistent_license| false indicates usage info record
+  // Adds a new entry to the OEMCrypto usage table header, and associates
+  // the entry with the provided |crypto_session|.  The index of the new
+  // usage entry will be returned by |usage_entry_number|.
+  //
+  // Type of entry depends on the value of |persistent_license|:
+  //    false - usage info / secure stop record
+  //    true  - offline license
+  //
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|.
   virtual CdmResponseType AddEntry(CryptoSession* crypto_session,
                                    bool persistent_license,
                                    const CdmKeySetId& key_set_id,
                                    const std::string& usage_info_filename,
                                    const CdmKeyResponse& license_message,
                                    uint32_t* usage_entry_number);
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|.
   virtual CdmResponseType LoadEntry(CryptoSession* crypto_session,
                                     const CdmUsageEntry& usage_entry,
                                     uint32_t usage_entry_number);
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|.
   virtual CdmResponseType UpdateEntry(uint32_t usage_entry_number,
                                       CryptoSession* crypto_session,
                                       CdmUsageEntry* usage_entry);
@@ -80,6 +92,8 @@ class UsageTableHeader {
   // to InvalidateEntry and MoveEntry are made.
   // If |defrag_table| is true, the table will be defragmented after
   // the entry has been invalidated.
+  //
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|.
   virtual CdmResponseType InvalidateEntry(uint32_t usage_entry_number,
                                           bool defrag_table,
                                           DeviceFiles* device_files,
@@ -91,8 +105,14 @@ class UsageTableHeader {
   // when InvalidateEntry is mocked. This allows one to test methods that are
   // dependent on InvalidateEntry without having to set expectations
   // for the objects that InvalidateEntry depends on.
+  //
+  // Threading: Method requires care of caller for exclusive access.
   void InvalidateEntryForTest(uint32_t usage_entry_number);
 
+  // == Table information methods ==
+  // Threading: None of the following are thread safe.  Intended for
+  // testing or internal use.
+
   size_t size() { return usage_entry_info_.size(); }
 
   size_t potential_table_capacity() const { return potential_table_capacity_; }
@@ -135,27 +155,36 @@ class UsageTableHeader {
 
   // Creates a new, empty usage table.  Any existing usage table files
   // will be deleted.
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|
+  // when required.
   bool CreateNewTable(CryptoSession* const crypto_session);
   // Attempts to restore the usage table from persistent storage, and
   // loads the usage table header into OEMCrypto.
   // Note: No other OEMCrypto session should be opened before calling.
+  // Threading: Method takes exclusive use of |usage_table_header_lock_|
+  // when required.
   bool RestoreTable(CryptoSession* const crypto_session);
 
   // Performs a check that there are no open OEMCrypto sessions for
   // the current security level of the usage table.
+  // Threading: No special threading requirements.
   bool OpenSessionCheck(CryptoSession* const crypto_session);
   // Performs a check that the OEMCrypto table can support at least
   // one more entry if the table is at or near the reported capacity.
   // If this check fails, a new usage table SHOULD be created.
+  // Threading: Method requires caller to take exclusive use of
+  // |usage_table_header_lock_|.
   bool CapacityCheck(CryptoSession* const crypto_session);
 
   // Attempts to determine the capacity of the OEMCrypto usage table.
   // Sets the result to |potential_table_capacity_|.
+  // Threading: Method requires caller to take exclusive use of
+  // |usage_table_header_lock_|.
   bool DetermineTableCapacity(CryptoSession* crypto_session);
 
   // == Table operation methods ==
-  // NOTE: The following "Table operation methods" require
+  // Threading: All of the following methods require caller to take
-  // |usage_table_header_lock_| to be taken before calling.
+  // exclusive use of |usage_table_header_lock_|.
 
   // Creates a new entry for the provided crypto session.  If the
   // entry is created successfully in OEMCrypto, then a new entry

libwvdrmengine/cdm/core/src/usage_table_header.cpp

@@ -170,11 +170,10 @@ bool UsageTableHeader::Init(CdmSecurityLevel security_level,
     return false;
   }
   if (!IsValidCdmSecurityLevelForUsageInfo(security_level)) {
-    LOGE("Invalid security level provided: security_level = %d",
+    LOGE("Invalid security level provided: security_level = %s",
-         static_cast<int>(security_level));
+         CdmSecurityLevelToString(security_level));
     return false;
   }
-
   security_level_ = security_level;
   requested_security_level_ = CdmSecurityLevelToRequestedLevel(security_level);