Merge pull request #15901 from Microsoft/10662-revendorhcs

Windows: Revendor HCSShim with godoc

hack/vendor.sh

@@ -14,7 +14,7 @@ clone git github.com/gorilla/context 14f550f51a
 clone git github.com/gorilla/mux e444e69cbd
 clone git github.com/kr/pty 5cf931ef8f
 clone git github.com/mattn/go-sqlite3 b4142c444a8941d0d92b0b7103a24df9cd815e42
-clone git github.com/microsoft/hcsshim da093dac579302d7b413696b96dec0b5e1bce8d4
+clone git github.com/microsoft/hcsshim 7f646aa6b26bcf90caee91e93cde4a80d0d8a83e
 clone git github.com/mistifyio/go-zfs v2.1.1
 clone git github.com/tchap/go-patricia v2.1.0
 clone git golang.org/x/net 3cffabab72adf04f8e3b01c5baf775361837b5fe https://github.com/golang/net.git

vendor/src/github.com/microsoft/hcsshim/activatelayer.go

@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ActivateLayer will find the layer with the given id and mount it's filesystem.
+// For a read/write layer, the mounted filesystem will appear as a volume on the
+// host, while a read-only layer is generally expected to be a no-op.
+// An activated layer must later be deactivated via DeactivateLayer.
 func ActivateLayer(info DriverInfo, id string) error {
 	title := "hcsshim::ActivateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)

vendor/src/github.com/microsoft/hcsshim/copylayer.go

@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CopyLayer performs a commit of the srcId (which is expected to be a read-write
+// layer) into a new read-only layer at dstId.  This requires the full list of
+// on-disk paths to parent layers, provided in parentLayerPaths, in order to
+// complete the commit.
 func CopyLayer(info DriverInfo, srcId, dstId string, parentLayerPaths []string) error {
 	title := "hcsshim::CopyLayer "
 	logrus.Debugf(title+"srcId %s dstId", srcId, dstId)

vendor/src/github.com/microsoft/hcsshim/createcomputesystem.go

@@ -8,7 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// CreateComputeSystem creates a container
+// CreateComputeSystem creates a container, initializing its configuration in
+// the Host Compute Service such that it can be started by a call to the
+// StartComputeSystem method.
 func CreateComputeSystem(id string, configuration string) error {
 
 	title := "HCSShim::CreateComputeSystem"

vendor/src/github.com/microsoft/hcsshim/createlayer.go

@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CreateLayer creates a new, empty, read-only layer on the filesystem based on
+// the parent layer provided.
 func CreateLayer(info DriverInfo, id, parent string) error {
 	title := "hcsshim::CreateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s parent %s", info.Flavour, id, parent)

vendor/src/github.com/microsoft/hcsshim/createprocess.go

@@ -11,7 +11,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// processParameters is use to both the input of CreateProcessInComputeSystem
+// CreateProcessParams is used as both the input of CreateProcessInComputeSystem
 // and to convert the parameters to JSON for passing onto the HCS
 type CreateProcessParams struct {
 	ApplicationName  string

vendor/src/github.com/microsoft/hcsshim/createsandboxlayer.go

@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// CreateSandboxLayer creates and populates new read-write layer for use by a container.
+// This requires both the id of the direct parent layer, as well as the full list
+// of paths to all parent layers up to the base (and including the direct parent
+// whose id was provided).
 func CreateSandboxLayer(info DriverInfo, layerId, parentId string, parentLayerPaths []string) error {
 	title := "hcsshim::CreateSandboxLayer "
 	logrus.Debugf(title+"layerId %s parentId %s", layerId, parentId)

vendor/src/github.com/microsoft/hcsshim/deactivatelayer.go

@@ -8,6 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// DeactivateLayer will dismount a layer that was mounted via ActivateLayer.
 func DeactivateLayer(info DriverInfo, id string) error {
 	title := "hcsshim::DeactivateLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)

vendor/src/github.com/microsoft/hcsshim/destroylayer.go

@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// DestroyLayer will remove the on-disk files representing the layer with the given
+// id, including that layer's containing folder, if any.
 func DestroyLayer(info DriverInfo, id string) error {
 	title := "hcsshim::DestroyLayer "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)

vendor/src/github.com/microsoft/hcsshim/exportlayer.go

@@ -8,6 +8,11 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ExportLayer will create a folder at exportFolderPath and fill that folder with
+// the transport format version of the layer identified by layerId. This transport
+// format includes any metadata required for later importing the layer (using
+// ImportLayer), and requires the full list of parent layer paths in order to
+// perform the export.
 func ExportLayer(info DriverInfo, layerId string, exportFolderPath string, parentLayerPaths []string) error {
 	title := "hcsshim::ExportLayer "
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, exportFolderPath)

vendor/src/github.com/microsoft/hcsshim/getlayermountpath.go

@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// GetLayerMountPath will look for a mounted layer with the given id and return
+// the path at which that layer can be accessed.  This path may be a volume path
+// if the layer is a mounted read-write layer, otherwise it is expected to be the
+// folder path at which the layer is stored.
 func GetLayerMountPath(info DriverInfo, id string) (string, error) {
 	title := "hcsshim::GetLayerMountPath "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)

vendor/src/github.com/microsoft/hcsshim/getsharedbaseimages.go

@@ -8,6 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// GetSharedBaseImages will enumerate the images stored in the common central
+// image store and return descriptive info about those images for the purpose
+// of registering them with the graphdriver, graph, and tagstore.
 func GetSharedBaseImages() (imageData string, err error) {
 	title := "hcsshim::GetSharedBaseImages "
 

vendor/src/github.com/microsoft/hcsshim/importlayer.go

@@ -8,6 +8,10 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ImportLayer will take the contents of the folder at importFolderPath and import
+// that into a layer with the id layerId.  Note that in order to correctly populate
+// the layer and interperet the transport format, all parent layers must already
+// be present on the system at the paths provided in parentLayerPaths.
 func ImportLayer(info DriverInfo, layerId string, importFolderPath string, parentLayerPaths []string) error {
 	title := "hcsshim::ImportLayer "
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, importFolderPath)

vendor/src/github.com/microsoft/hcsshim/layerexists.go

@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// LayerExists will return true if a layer with the given id exists and is known
+// to the system.
 func LayerExists(info DriverInfo, id string) (bool, error) {
 	title := "hcsshim::LayerExists "
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)

vendor/src/github.com/microsoft/hcsshim/nametoguid.go

@@ -8,6 +8,9 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// NameToGuid converts the given string into a GUID using the algorithm in the
+// Host Compute Service, ensuring GUIDs generated with the same string are common
+// across all clients.
 func NameToGuid(name string) (id GUID, err error) {
 	title := "hcsshim::NameToGuid "
 	logrus.Debugf(title+"Name %s", name)

vendor/src/github.com/microsoft/hcsshim/preparelayer.go

@@ -8,6 +8,11 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// PrepareLayer finds a mounted read-write layer matching layerId and enables the
+// the filesystem filter for use on that layer.  This requires the paths to all
+// parent layers, and is necessary in order to view or interact with the layer
+// as an actual filesystem (reading and writing files, creating directories, etc).
+// Disabling the filter must be done via UnprepareLayer.
 func PrepareLayer(info DriverInfo, layerId string, parentLayerPaths []string) error {
 	title := "hcsshim::PrepareLayer "
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)

vendor/src/github.com/microsoft/hcsshim/resizeconsole.go

@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// ResizeConsoleInComputeSystem updates the height and width of the console
+// session for the process with the given id in the container with the given id.
 func ResizeConsoleInComputeSystem(id string, processid uint32, h, w int) error {
 
 	title := "HCSShim::ResizeConsoleInComputeSystem"

vendor/src/github.com/microsoft/hcsshim/shutdowncomputesystem.go

@@ -8,7 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// ShutdownComputeSystem shuts down a container
+// ShutdownComputeSystem shuts down a container by requesting a shutdown within
+// the container operating system.
 func ShutdownComputeSystem(id string) error {
 
 	var title = "HCSShim::ShutdownComputeSystem"

vendor/src/github.com/microsoft/hcsshim/startcomputesystem.go

@@ -8,7 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// StartComputeSystem starts a container
+// StartComputeSystem starts a container that has previously been created via
+// CreateComputeSystem.
 func StartComputeSystem(id string) error {
 
 	title := "HCSShim::StartComputeSystem"

vendor/src/github.com/microsoft/hcsshim/terminatecomputesystem.go

@@ -8,7 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// TerminateComputeSystem force terminates a container
+// TerminateComputeSystem force terminates a container.
 func TerminateComputeSystem(id string) error {
 
 	var title = "HCSShim::TerminateComputeSystem"

vendor/src/github.com/microsoft/hcsshim/terminateprocess.go

@@ -8,7 +8,7 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
-// TerminateProcessInComputeSystem kills a process in a running container
+// TerminateProcessInComputeSystem kills a process in a running container.
 func TerminateProcessInComputeSystem(id string, processid uint32) (err error) {
 
 	title := "HCSShim::TerminateProcessInComputeSystem"

vendor/src/github.com/microsoft/hcsshim/unpreparelayer.go

@@ -8,6 +8,8 @@ import (
 	"github.com/Sirupsen/logrus"
 )
 
+// UnprepareLayer disables the filesystem filter for the read-write layer with
+// the given id.
 func UnprepareLayer(info DriverInfo, layerId string) error {
 	title := "hcsshim::UnprepareLayer "
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)