From 09b5463d9bcdd7b9562838e0b44029b6c04c487d Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 2 Jul 2015 12:56:51 +1000 Subject: [PATCH] doc: finish the small library changes in go1.5.html; start work on tools Also add words about the assembler. Change-Id: I9bd8cc88076f06b0eef36a07f57d1ad5d9261d8d Reviewed-on: https://go-review.googlesource.com/11853 Reviewed-by: Brad Fitzpatrick --- doc/go1.5.html | 252 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 220 insertions(+), 32 deletions(-) diff --git a/doc/go1.5.html b/doc/go1.5.html index 879203bbfe..4270fa3398 100644 --- a/doc/go1.5.html +++ b/doc/go1.5.html @@ -241,30 +241,86 @@ cmd/gc: add -dynlink option (for amd64 only) cmd/ld: add -buildmode option cmd/trace: new command to view traces (https://golang.org/cl/3601) -Assembler: + -New cmd/asm tool (now use go tool asm, not go tool 6a) +

Assembler

-Assembler now supports -dynlink option. +

+The assembler in Go 1.5 is a single new Go program that replaces +the suite of C-language assemblers (6a, +8a, etc.) in previous releases. +The values of the environmetn variables +GOARCH and GOOS +choose which architecture and operating system the generated +code will be for. +This is practical because the assembly language syntax has always +been idiosyncratic and nearly uniform across architectures; +what differs is just the list of instructions available and the +syntax of some addressing modes. +With the variation easily configured at startup, a single +assembler binary can cover all architectures. +(See the updated assembler guide +for more information about the language and some of +the changes listed below.) +

+ +

+The new assembler is very nearly compatible with the previous +one, but there are a few changes that may affect some +assembler source files. +

-ARM assembly syntax has had some features removed. +

+First, the expression evaluation used for constants is a little +different. +It now uses unsigned 64-bit arithmetic and the precedence +of operators (+, -, <<, etc.) +comes from Go, not C. +Since there are few assembly programs to start with, and few use +complex arithmetic expressions, +and of those even fewer will be affected by these changes, we expect +almost no programs will need to be updated. +

- - mentioning SP or PC as a hardware register - These are always pseudo-registers except that in some contexts - they're not, and it's confusing because the context should not affect - which register you mean. Change the references to the hardware - registers to be explicit: R13 for SP, R15 for PC. - - constant creation using assignment - The files say a=b when they could instead say #define a b. - There is no reason to have both mechanisms. - - R(0) to refer to R0. - Some macros use this to a great extent. Again, it's easy just to - use a #define to rename a register. +

+Perhaps more important is that some discrepancies between the +architectures in how the PC and SP are handled have been +eliminated. +Sometimes these registers represented hardware +registers, and sometimes pseudo-registers. +As of Go 1.5, the names PC and SP +are always pseudo-registers. +To refer to the hardware register, use the alternate representation such +as R13 for the stack pointer and +R15 for the hardware program counter on x86. +(The names are different on other architectures.) +To help enforce this change, references to the +SP and PC +pseudo-registers now always require an identifier: +f+4(SP) not 4(SP); +it is a syntax error to omit the identifier. +Uses of SP (say) as a hardware register +tend to omit the name, and they will now be flagged by +the assembler. +

+ +

+One minor change is that some of the old assemblers +permitted the notation +

-Also expression evaluation now uses uint64s instead of signed integers and the -precedence of operators is now Go-like rather than C-like. +
+constant=value
+

+to define a named constant. +Since this is always possible to do with the traditional +C-like #define notation, which is still +supported (the assembler includes an implementation +of a simplified C preprocessor), the feature was removed. +

+

Performance

@@ -465,43 +521,86 @@ function that locates the rightmost byte with that value in the argument.
 
 
 
  • 
-TODO crypto/cipher: clarify what will happen if len(src) != len(dst) for the Stream interface. (https://golang.org/cl/1754)
+The crypto package
+has a new interface, Decrypter,
+that abstracts the behavior of a private key used in asymmetric decryption.
 
    • 
 
 
  • 
-TODO crypto/cipher: support non-standard nonce lengths for GCM. (https://golang.org/cl/8946)
+In the crypto/cipher package,
+the documentation for the Stream
+interface has been clarified regarding the behavior when the source and destination are
+different lengths.
+If the destination is shorter than the source, the method will panic.
+This is not a change in the implementation, only the documentation.
 
    • 
 
 
  • 
-TODO crypto/elliptic: add Name field to CurveParams struct (https://golang.org/cl/2133)
+Also in the crypto/cipher package,
+there is now support for nonce lengths other than 96 bytes in AES's Galois/Counter mode (GCM),
+which some protocols require.
 
    • 
 
 
  • 
-TODO crypto/elliptic: Unmarshaling points now automatically checks that the point is on the curve (https://golang.org/cl/2421)
+In the crypto/elliptic package,
+there is now a Name field in the
+CurveParams struct,
+and the curves implemented in the package have been given names.
+These names provide a safer way to select a curve, as opposed to
+selecting its bit size, for cryptographic systems that are curve-dependent.
 
    • 
 
 
  • 
-TODO crypto/tls: change default minimum version to TLS 1.0. (https://golang.org/cl/1791)
+Also in the crypto/elliptic package,
+the Unmarshal function
+now verifies that the point is actually on the curve.
+(If it is not, the function returns nils).
+This change guards against certain attacks.
 
    • 
 
 
  • 
-TODO crypto/tls: including Certificate Transparency SCTs in the handshake is now supported (https://golang.org/cl/8988)
+The crypto/tls package
+now defaults to TLS 1.0.
+The old default, SSLv3, is still available through Config if needed.
 
    • 
 
 
  • 
-TODO crypto/tls: session ticket keys can now be rotated at runtime (https://golang.org/cl/9072)
+Also, the crypto/tls package
+now supports Signed Certificate Timestamps (SCTs) as specified in RFC 6962.
+The server serves them if they are listed in the
+Certificate struct,
+and the client reqeusts them and exposes them, if present,
+in its ConnectionState struct.
+The crytpo/tls server implementation
+will also now always call the
+GetCertificate function in
+the Config struct
+to select a certificate for the connection when none is supplied.
 
    • 
 
 
  • 
-TODO crypto/tls: servers will now always call GetCertificate to pick a certificate for a connection when Certificates is empty (https://golang.org/cl/8792)
+Finally, the session ticket keys in the
+crypto/tls package
+can now be rotated (changed periodically during an active connection).
+This is done through the new 
+SetSessionTicketKeys
+method of the
+Config type.
 
    • 
 
 
  • 
-TODO crypto/x509: wildcards are now only accepted as the first label (https://golang.org/cl/5691)
+In the crypto/x509 package,
+wildcards are now accepted only in the leftmost label as defined in
+the specification.
 
    • 
 
 
  • 
-TODO crypto/x509: unknown critical extensions now cause errors in Verify, not when parsing (https://golang.org/cl/9390)
+Also in the crypto/x509 package,
+the handling of unknown critical extensions has been changed.
+They used to cause parse errors but now they are parsed and caused errors only
+in Verify.
+The new field UnhandledCriticalExtensions of
+Certificate records these extensions.
 
    • 
 
 
  • 
@@ -511,6 +610,18 @@ now has a Stats method
 to retrieve database statistics.
 
    • 
 
+
  • 
+The debug/dwarf
+package has extensive additions to better support DWARF version 4.
+See for example the definition of the new type
+Class.
+
    • 
+
+
  • 
+The debug/elf
+package now has support for the 64-bit Power architecture.
+
    • 
+
 
  • 
 The encoding/base64 package
 now supports unpadded encodings through two new encoding variables,
@@ -518,6 +629,20 @@ now supports unpadded encodings through two new encoding variables,
 RawURLEncoding.
 
    • 
 
+
  • 
+The encoding/json package
+now returns an UnmarshalTypeError
+if a JSON value is not appropriate for the target variable or component
+to which it is being unmarshaled.
+
    • 
+
+
  • 
+The flag package
+has a new function, UnquoteUsage,
+to assist in the creation of usage messages using the new convention
+described above.
+
    • 
+
 
  • 
 Also in the fmt package,
 a value of type Value now
@@ -536,6 +661,9 @@ semicolon was implicitly added or was present in the source.
 For forward compatibility the go/build package
 reserves GOARCH values for  a number of architectures that Go might support one day.
 This is not a promise that it will.
+Also, the Package struct
+now has a PkgTargetRoot field that stores the
+architecture-dependent root directory in which to install, if known.
 
    • 
 
 
  • 
@@ -548,6 +676,39 @@ rules since code that uses the package must explicitly ask for it at its new loc
 TODO: There should be a gofix for this.
 
    • 
 
+
  • 
+In the image package,
+the Rectangle type
+now implements the Image interface,
+mask image when drawing.
+
    • 
+
+
  • 
+Also in the image package,
+to assist in the handling of some JPEG images,
+there is now support for 4:1:1 and 4:1:0 YCbCr subsampling and basic
+CMYK support, represented by the new image.CMYK struct.
+
    • 
+
+
  • 
+The image/color package
+adds basic CMYK support, through the new
+CMYK struct,
+the CMYKModel color model, and the
+CMYKToRGB function, as
+needed by some JPEG images.
+
    • 
+
+
  • 
+The image/gif package
+includes a couple of generalizations.
+A multiple-frame GIF file can now have an overall bounds different
+from all the contained single frames' bounds.
+Also, the GIF struct
+now has a Disposal field
+that specifies the disposal method for each frame.
+
    • 
+
 
  • 
 The io package
 adds a CopyBuffer function
@@ -579,7 +740,16 @@ method for the Int type.
 
    • 
 
 
  • 
-The mime package adds an
+The mime package
+adds a new WordDecoder type
+to decode MIME headers containing RFC 204-encoded words.
+It also provides BEncoding and
+QEncoding
+as implementations of the encoding schemes of RFC 2045 and RFC 2047.
+
    • 
+
+
  • 
+The mime package also adds an
 ExtensionsByType
 function that returns the MIME extensions know to be associated with a given MIME type.
 
    • 
@@ -609,10 +779,6 @@ type now includes a Source field that holds the local
 network address.
 
 
-
  • 
-TODO net: add SocketConn, SocketPacketConn (https://golang.org/cl/9275)
-
    • 
-
 
  • 
 The net/http package now
 has support for setting trailers from a server Handler.
@@ -627,6 +793,14 @@ in the ServeContent function.
 As of Go 1.5, it now also ignores a time value equal to the Unix epoch.
 
    • 
 
+
  • 
+The net/http/fcgi package
+exports two new errors,
+ErrConnClosed and
+ErrRequestAborted,
+to report the corresponding error conditions.
+
    • 
+
 
  • 
 The net/http/cgi package
 had a bug that mishandled the values of the environment variables
@@ -662,6 +836,20 @@ adds new Ignore and
 Reset functions.
 
    • 
 
+
  • 
+The runtime,
+runtime/pprof,
+and net/http/pprof packages
+each have new functions to support the tracing facilities described above:
+ReadTrace,
+StartTrace,
+StopTrace,
+StartTrace,
+StopTrace, and
+Trace.
+See the respective documentation for details.
+
    • 
+
 
  • 
 The runtime/pprof package
 by default now includes overall memory statistics in all memory profiles.
-- 
2.50.0